-# Allow Location Descriptions on the DWARF Expression Stack <!-- omit in toc -->\r
-\r
-- [1. Extension](#extension)\r
-- [2. Heterogeneous Computing Devices](#heterogeneous-computing-devices)\r
-- [3. DWARF 5](#dwarf-5)\r
- - [3.1 How DWARF Maps Source Language To Hardware](#how-dwarf-maps-source-language-to-hardware)\r
- - [3.2 Examples](#examples)\r
- - [3.2.1 Dynamic Array Size](#dynamic-array-size)\r
- - [3.2.2 Variable Location in Register](#variable-location-in-register)\r
- - [3.2.3 Variable Location in Memory](#variable-location-in-memory)\r
- - [3.2.4 Variable Spread Across Different Locations](#variable-spread-across-different-locations)\r
- - [3.2.5 Offsetting a Composite Location](#offsetting-a-composite-location)\r
- - [3.3 Limitations](#limitations)\r
-- [4. Extension Solution](#extension-solution)\r
- - [4.1 Location Description](#location-description)\r
- - [4.2 Stack Location Description Operations](#stack-location-description-operations)\r
- - [4.3 Examples](#examples-1)\r
- - [4.3.1 Source Language Variable Spilled to Part of a Vector Register](#source-language-variable-spilled-to-part-of-a-vector-register)\r
- - [4.3.2 Source Language Variable Spread Across Multiple Vector Registers](#source-language-variable-spread-across-multiple-vector-registers)\r
- - [4.3.3 Source Language Variable Spread Across Multiple Kinds of Locations](#source-language-variable-spread-across-multiple-kinds-of-locations)\r
- - [4.3.4 Address Spaces](#address-spaces)\r
- - [4.3.5 Bit Offsets](#bit-offsets)\r
- - [4.4 Call Frame Information (CFI)](#call-frame-information-cfi)\r
- - [4.5 Objects Not In Byte Aligned Global Memory](#objects-not-in-byte-aligned-global-memory)\r
- - [4.6 Higher Order Operations](#higher-order-operations)\r
- - [4.7 Objects In Multiple Places](#objects-in-multiple-places)\r
-- [5. Conclusion](#conclusion)\r
-- [A. Changes to DWARF Debugging Information Format Version 5](#a-changes-to-dwarf-debugging-information-format-version-5)\r
- - [A.2 General Description](#a-2-general-description)\r
- - [A.2.5 DWARF Expressions](#a-2-5-dwarf-expressions)\r
- - [A.2.5.1 DWARF Expression Evaluation Context](#a-2-5-1-dwarf-expression-evaluation-context)\r
- - [A.2.5.2 DWARF Expression Value](#a-2-5-2-dwarf-expression-value)\r
- - [A.2.5.3 DWARF Location Description](#a-2-5-3-dwarf-location-description)\r
- - [A.2.5.4 DWARF Operation Expressions](#a-2-5-4-dwarf-operation-expressions)\r
- - [A.2.5.4.1 Stack Operations](#a-2-5-4-1-stack-operations)\r
- - [A.2.5.4.2 Control Flow Operations](#a-2-5-4-2-control-flow-operations)\r
- - [A.2.5.4.3 Value Operations](#a-2-5-4-3-value-operations)\r
- - [A.2.5.4.3.1 Literal Operations](#a-2-5-4-3-1-literal-operations)\r
- - [A.2.5.4.3.2 Arithmetic and Logical Operations](#a-2-5-4-3-2-arithmetic-and-logical-operations)\r
- - [A.2.5.4.3.3 Type Conversion Operations](#a-2-5-4-3-3-type-conversion-operations)\r
- - [A.2.5.4.3.4 Special Value Operations](#a-2-5-4-3-4-special-value-operations)\r
- - [A.2.5.4.4 Location Description Operations](#a-2-5-4-4-location-description-operations)\r
- - [A.2.5.4.4.1 General Location Description Operations](#a-2-5-4-4-1-general-location-description-operations)\r
- - [A.2.5.4.4.2 Undefined Location Description Operations](#a-2-5-4-4-2-undefined-location-description-operations)\r
- - [A.2.5.4.4.3 Memory Location Description Operations](#a-2-5-4-4-3-memory-location-description-operations)\r
- - [A.2.5.4.4.4 Register Location Description Operations](#a-2-5-4-4-4-register-location-description-operations)\r
- - [A.2.5.4.4.5 Implicit Location Description Operations](#a-2-5-4-4-5-implicit-location-description-operations)\r
- - [A.2.5.4.4.6 Composite Location Description Operations](#a-2-5-4-4-6-composite-location-description-operations)\r
- - [A.2.5.5 DWARF Location List Expressions](#a-2-5-5-dwarf-location-list-expressions)\r
- - [A.3 Program Scope Entries](#a-3-program-scope-entries)\r
- - [A.3.3 Subroutine and Entry Point Entries](#a-3-3-subroutine-and-entry-point-entries)\r
- - [A.3.3.5 Low-Level Information](#a-3-3-5-low-level-information)\r
- - [A.3.4 Call Site Entries and Parameters](#a-3-4-call-site-entries-and-parameters)\r
- - [A.3.4.2 Call Site Parameters](#a-3-4-2-call-site-parameters)\r
- - [A.3.5 Lexical Block Entries](#a-3-5-lexical-block-entries)\r
- - [A.4 Data Object and Object List Entries](#a-4-data-object-and-object-list-entries)\r
- - [A.4.1 Data Object Entries](#a-4-1-data-object-entries)\r
- - [A.5 Type Entries](#a-5-type-entries)\r
- - [A.5.7 Structure, Union, Class and Interface Type Entries](#a-5-7-structure-union-class-and-interface-type-entries)\r
- - [A.5.7.3 Derived or Extended Structures, Classes and Interfaces](#a-5-7-3-derived-or-extended-structures-classes-and-interfaces)\r
- - [A.5.7.8 Member Function Entries](#a-5-7-8-member-function-entries)\r
- - [A.5.14 Pointer to Member Type Entries](#a-5-14-pointer-to-member-type-entries)\r
- - [A.5.16 Dynamic Type Entries](#a-5-16-dynamic-type-entries)\r
- - [A.6 Other Debugging Information](#a-6-other-debugging-information)\r
- - [A.6.2 Line Number Information](#a-6-2-line-number-information)\r
- - [A.6.4 Call Frame Information](#a-6-4-call-frame-information)\r
- - [A.6.4.1 Structure of Call Frame Information](#a-6-4-1-structure-of-call-frame-information)\r
- - [A.6.4.2 Call Frame Instructions](#a-6-4-2-call-frame-instructions)\r
- - [A.6.4.2.1 Row Creation Instructions](#a-6-4-2-1-row-creation-instructions)\r
- - [A.6.4.2.2 CFA Definition Instructions](#a-6-4-2-2-cfa-definition-instructions)\r
- - [A.6.4.2.3 Register Rule Instructions](#a-6-4-2-3-register-rule-instructions)\r
- - [A.6.4.2.4 Row State Instructions](#a-6-4-2-4-row-state-instructions)\r
- - [A.6.4.2.5 Padding Instruction](#a-6-4-2-5-padding-instruction)\r
- - [A.6.4.3 Call Frame Instruction Usage](#a-6-4-3-call-frame-instruction-usage)\r
- - [A.6.4.4 Call Frame Calling Address](#a-6-4-4-call-frame-calling-address)\r
- - [A.7 Data Representation](#a-7-data-representation)\r
- - [A.7.4 32-Bit and 64-Bit DWARF Formats](#a-7-4-32-bit-and-64-bit-dwarf-formats)\r
- - [A.7.5 Format of Debugging Information](#a-7-5-format-of-debugging-information)\r
- - [A.7.5.5 Classes and Forms](#a-7-5-5-classes-and-forms)\r
- - [A.7.7 DWARF Expressions](#a-7-7-dwarf-expressions)\r
- - [A.7.7.1 Operation Expressions](#a-7-7-1-operation-expressions)\r
- - [A.7.7.3 Location List Expressions](#a-7-7-3-location-list-expressions)\r
-- [B. Further Information](#b-further-information)\r
-\r
-# 1. Extension\r
-\r
-In DWARF 5, expressions are evaluated using a typed value stack, a separate\r
-location area, and an independent loclist mechanism. This extension unifies all\r
-three mechanisms into a single generalized DWARF expression evaluation model\r
-that allows both typed values and location descriptions to be manipulated on the\r
-evaluation stack. Both single and multiple location descriptions are supported\r
-on the stack. In addition, the call frame information (CFI) is extended to\r
-support the full generality of location descriptions. This is done in a manner\r
-that is backwards compatible with DWARF 5. The extension involves changes to the\r
-DWARF 5 sections 2.5 (pp 26-38), 2.6 (pp 38-45), and 6.4 (pp 171-182).\r
-\r
-The extension permits operations to act on location descriptions in an\r
-incremental, consistent, and composable manner. It allows a small number of\r
-operations to be defined to address the requirements of heterogeneous devices as\r
-well as providing benefits to non-heterogeneous devices. It acts as a foundation\r
-to provide support for other issues that have been raised that would benefit all\r
-devices.\r
-\r
-Other approaches were explored that involved adding specialized operations and\r
-rules. However, these resulted in the need for more operations that did not\r
-compose. It also resulted in operations with context sensitive semantics and\r
-corner cases that had to be defined. The observation was that numerous\r
-specialized context sensitive operations are harder for both produces and\r
-consumers than a smaller number of general composable operations that have\r
-consistent semantics regardless of context.\r
-\r
-First, section [2. Heterogeneous Computing\r
-Devices](#heterogeneous-computing-devices) describes heterogeneous devices and\r
-the features they have that are not addressed by DWARF 5. Then section [3. DWARF\r
-5](#dwarf-5) presents a brief simplified overview of the DWARF 5 expression\r
-evaluation model that highlights the difficulties for supporting the\r
-heterogeneous features. Next, section [4. Extension\r
-Solution](#extension-solution) provides an overview of the proposal, using\r
-simplified examples to illustrate how it can address the issues of heterogeneous\r
-devices and also benefit non-heterogeneous devices. Then overall conclusions are\r
-covered in section [5. Conclusion](#conclusion). Appendix [A. Changes to DWARF\r
-Debugging Information Format Version\r
-5](#a-changes-to-dwarf-debugging-information-format-version-5) gives changes\r
-relative to the DWARF Version 5 standard. Finally, appendix [B. Further\r
-Information](#b-further-information) has references to further information.\r
-\r
-# 2. Heterogeneous Computing Devices\r
-\r
-GPUs and other heterogeneous computing devices have features not common to CPU\r
-computing devices.\r
-\r
-These devices often have many more registers than a CPU. This helps reduce\r
-memory accesses which tend to be more expensive than on a CPU due to the much\r
-larger number of threads concurrently executing. In addition to traditional\r
-scalar registers of a CPU, these devices often have many wide vector registers.\r
-\r
-\r
-\r
-They may support masked vector instructions that are used by the compiler to map\r
-high level language threads onto the lanes of the vector registers. As a\r
-consequence, multiple language threads execute in lockstep as the vector\r
-instructions are executed. This is termed single instruction multiple thread\r
-(SIMT) execution.\r
-\r
-\r
-\r
-GPUs can have multiple memory address spaces in addition to the single global\r
-memory address space of a CPU. These additional address spaces are accessed\r
-using distinct instructions and are often local to a particular thread or group\r
-of threads.\r
-\r
-For example, a GPU may have a per thread block address space that is implemented\r
-as scratch pad memory with explicit hardware support to isolate portions to\r
-specific groups of threads created as a single thread block.\r
-\r
-A GPU may also use global memory in a non linear manner. For example, to support\r
-providing a SIMT per lane address space efficiently, there may be instructions\r
-that support interleaved access.\r
-\r
-Through optimization, the source variables may be located across these different\r
-storage kinds. SIMT execution requires locations to be able to express selection\r
-of runtime defined pieces of vector registers. With the more complex locations,\r
-there is a benefit to be able to factorize their calculation which requires all\r
-location kinds to be supported uniformly, otherwise duplication is necessary.\r
-\r
-# 3. DWARF 5\r
-\r
-Before presenting the proposed solution to supporting heterogeneous devices, a\r
-brief overview of the DWARF 5 expression evaluation model will be given to\r
-highlight the aspects being addressed by the extension.\r
-\r
-## 3.1 How DWARF Maps Source Language To Hardware\r
-\r
-DWARF is a standardized way to specify debug information. It describes source\r
-language entities such as compilation units, functions, types, variables, etc.\r
-It is either embedded directly in sections of the code object executables, or\r
-split into separate files that they reference.\r
-\r
-DWARF maps between source program language entities and their hardware\r
-representations. For example:\r
-\r
-- It maps a hardware instruction program counter to a source language program\r
- line, and vice versa.\r
-- It maps a source language function to the hardware instruction program counter\r
- for its entry point.\r
-- It maps a source language variable to its hardware location when at a\r
- particular program counter.\r
-- It provides information to allow virtual unwinding of hardware registers for a\r
- source language function call stack.\r
-- In addition, it provides numerous other information about the source language\r
- program.\r
-\r
-In particular, there is great diversity in the way a source language entity\r
-could be mapped to a hardware location. The location may involve runtime values.\r
-For example, a source language variable location could be:\r
-\r
-- In register.\r
-- At a memory address.\r
-- At an offset from the current stack pointer.\r
-- Optimized away, but with a known compiler time value.\r
-- Optimized away, but with an unknown value, such as happens for unused\r
- variables.\r
-- Spread across combination of the above kinds of locations.\r
-- At a memory address, but also transiently loaded into registers.\r
-\r
-To support this DWARF 5 defines a rich expression language comprised of loclist\r
-expressions and operation expressions. Loclist expressions allow the result to\r
-vary depending on the PC. Operation expressions are made up of a list of\r
-operations that are evaluated on a simple stack machine.\r
-\r
-A DWARF expression can be used as the value of different attributes of different\r
-debug information entries (DIE). A DWARF expression can also be used as an\r
-argument to call frame information information (CFI) entry operations. An\r
-expression is evaluated in a context dictated by where it is used. The context\r
-may include:\r
-\r
-- Whether the expression needs to produce a value or the location of an entity.\r
-- The current execution point including process, thread, PC, and stack frame.\r
-- Some expressions are evaluated with the stack initialized with a specific\r
- value or with the location of a base object that is available using the\r
- DW_OP_push_object_address operation.\r
-\r
-## 3.2 Examples\r
-\r
-The following examples illustrate how DWARF expressions involving operations are\r
-evaluated in DWARF 5. DWARF also has expressions involving location lists that\r
-are not covered in these examples.\r
-\r
-### 3.2.1 Dynamic Array Size\r
-\r
-The first example is for an operation expression associated with a DIE attribute\r
-that provides the number of elements in a dynamic array type. Such an attribute\r
-dictates that the expression must be evaluated in the context of providing a\r
-value result kind.\r
-\r
-\r
-\r
-In this hypothetical example, the compiler has allocated an array descriptor in\r
-memory and placed the descriptor's address in architecture register SGPR0. The\r
-first location of the array descriptor is the runtime size of the array.\r
-\r
-A possible expression to retrieve the dynamic size of the array is:\r
-\r
- DW_OP_regval_type SGPR0 Generic\r
- DW_OP_deref\r
-\r
-The expression is evaluated one operation at a time. Operations have operands\r
-and can pop and push entries on a stack.\r
-\r
-\r
-\r
-The expression evaluation starts with the first DW_OP_regval_type operation.\r
-This operation reads the current value of an architecture register specified by\r
-its first operand: SGPR0. The second operand specifies the size of the data to\r
-read. The read value is pushed on the stack. Each stack element is a value and\r
-its associated type.\r
-\r
-\r
-\r
-The type must be a DWARF base type. It specifies the encoding, byte ordering,\r
-and size of values of the type. DWARF defines that each architecture has a\r
-default generic type: it is an architecture specific integral encoding and byte\r
-ordering, that is the size of the architecture's global memory address.\r
-\r
-The DW_OP_deref operation pops a value off the stack, treats it as a global\r
-memory address, and reads the contents of that location using the generic type.\r
-It pushes the read value on the stack as the value and its associated generic\r
-type.\r
-\r
-\r
-\r
-The evaluation stops when it reaches the end of the expression. The result of an\r
-expression that is evaluated with a value result kind context is the top element\r
-of the stack, which provides the value and its type.\r
-\r
-### 3.2.2 Variable Location in Register\r
-\r
-This example is for an operation expression associated with a DIE attribute that\r
-provides the location of a source language variable. Such an attribute dictates\r
-that the expression must be evaluated in the context of providing a location\r
-result kind.\r
-\r
-DWARF defines the locations of objects in terms of location descriptions.\r
-\r
-In this example, the compiler has allocated a source language variable in\r
-architecture register SGPR0.\r
-\r
-\r
-\r
-A possible expression to specify the location of the variable is:\r
-\r
- DW_OP_regx SGPR0\r
-\r
-\r
-\r
-The DW_OP_regx operation creates a location description that specifies the\r
-location of the architecture register specified by the operand: SGPR0. Unlike\r
-values, location descriptions are not pushed on the stack. Instead they are\r
-conceptually placed in a location area. Unlike values, location descriptions do\r
-not have an associated type, they only denote the location of the base of the\r
-object.\r
-\r
-\r
-\r
-Again, evaluation stops when it reaches the end of the expression. The result of\r
-an expression that is evaluated with a location result kind context is the\r
-location description in the location area.\r
-\r
-### 3.2.3 Variable Location in Memory\r
-\r
-The next example is for an operation expression associated with a DIE attribute\r
-that provides the location of a source language variable that is allocated in a\r
-stack frame. The compiler has placed the stack frame pointer in architecture\r
-register SGPR0, and allocated the variable at offset 0x10 from the stack frame\r
-base. The stack frames are allocated in global memory, so SGPR0 contains a\r
-global memory address.\r
-\r
-\r
-\r
-A possible expression to specify the location of the variable is:\r
-\r
- DW_OP_regval_type SGPR0 Generic\r
- DW_OP_plus_uconst 0x10\r
-\r
-\r
-\r
-As in the previous example, the DW_OP_regval_type operation pushes the stack\r
-frame pointer global memory address onto the stack. The generic type is the size\r
-of a global memory address.\r
-\r
-\r
-\r
-The DW_OP_plus_uconst operation pops a value from the stack, which must have a\r
-type with an integral encoding, adds the value of its operand, and pushes the\r
-result back on the stack with the same associated type. In this example, that\r
-computes the global memory address of the source language variable.\r
-\r
-\r
-\r
-Evaluation stops when it reaches the end of the expression. If the expression\r
-that is evaluated has a location result kind context, and the location area is\r
-empty, then the top stack element must be a value with the generic type. The\r
-value is implicitly popped from the stack, and treated as a global memory\r
-address to create a global memory location description, which is placed in the\r
-location area. The result of the expression is the location description in the\r
-location area.\r
-\r
-\r
-\r
-### 3.2.4 Variable Spread Across Different Locations\r
-\r
-This example is for a source variable that is partly in a register, partly undefined, and partly in memory.\r
-\r
-\r
-\r
-DWARF defines composite location descriptions that can have one or more parts.\r
-Each part specifies a location description and the number of bytes used from it.\r
-The following operation expression creates a composite location description.\r
-\r
- DW_OP_regx SGPR3\r
- DW_OP_piece 4\r
- DW_OP_piece 2\r
- DW_OP_bregx SGPR0 0x10\r
- DW_OP_piece 2\r
-\r
-\r
-\r
-The DW_OP_regx operation creates a register location description in the location\r
-area.\r
-\r
-\r
-\r
-The first DW_OP_piece operation creates an incomplete composite location\r
-description in the location area with a single part. The location description in\r
-the location area is used to define the beginning of the part for the size\r
-specified by the operand, namely 4 bytes.\r
-\r
-\r
-\r
-A subsequent DW_OP_piece adds a new part to an incomplete composite location\r
-description already in the location area. The parts form a contiguous set of\r
-bytes. If there are no other location descriptions in the location area, and no\r
-value on the stack, then the part implicitly uses the undefined location\r
-description. Again, the operand specifies the size of the part in bytes. The\r
-undefined location description can be used to indicate a part that has been\r
-optimized away. In this case, 2 bytes of undefined value.\r
-\r
-\r
-\r
-The DW_OP_bregx operation reads the architecture register specified by the first\r
-operand (SGPR0) as the generic type, adds the value of the second operand\r
-(0x10), and pushes the value on the stack.\r
-\r
-\r
-\r
-The next DW_OP_piece operation adds another part to the already created\r
-incomplete composite location.\r
-\r
-If there is no other location in the location area, but there is a value on\r
-stack, the new part is a memory location description. The memory address used is\r
-popped from the stack. In this case, the operand of 2 indicates there are 2\r
-bytes from memory.\r
-\r
-\r
-\r
-Evaluation stops when it reaches the end of the expression. If the expression\r
-that is evaluated has a location result kind context, and the location area has\r
-an incomplete composite location description, the incomplete composite location\r
-is implicitly converted to a complete composite location description. The result\r
-of the expression is the location description in the location area.\r
-\r
-\r
-\r
-### 3.2.5 Offsetting a Composite Location\r
-\r
-This example attempts to extend the previous example to offset the composite\r
-location description it created. The [3.2.3 Variable Location in\r
-Memory](#variable-location-in-memory) example conveniently used the DW_OP_plus\r
-operation to offset a memory address.\r
-\r
- DW_OP_regx SGPR3\r
- DW_OP_piece 4\r
- DW_OP_piece 2\r
- DW_OP_bregx SGPR0 0x10\r
- DW_OP_piece 2\r
- DW_OP_plus_uconst 5\r
-\r
-\r
-\r
-However, DW_OP_plus cannot be used to offset a composite location. It only\r
-operates on the stack.\r
-\r
-\r
-\r
-To offset a composite location description, the compiler would need to make a\r
-different composite location description, starting at the part corresponding to\r
-the offset. For example:\r
-\r
- DW_OP_piece 1\r
- DW_OP_bregx SGPR0 0x10\r
- DW_OP_piece 2\r
-\r
-This illustrates that operations on stack values are not composable with\r
-operations on location descriptions.\r
-\r
-## 3.3 Limitations\r
-\r
-DWARF 5 is unable to describe variables in runtime indexed parts of registers.\r
-This is required to describe a source variable that is located in a lane of a\r
-SIMT vector register.\r
-\r
-Some features only work when located in global memory. The type attribute\r
-expressions require a base object which could be in any kind of location.\r
-\r
-DWARF procedures can only accept global memory address arguments. This limits\r
-the ability to factorize the creation of locations that involve other location\r
-kinds.\r
-\r
-There are no vector base types. This is required to describe vector registers.\r
-\r
-There is no operation to create a memory location in a non-global address space.\r
-Only the dereference operation supports providing an address space.\r
-\r
-CFI location expressions do not allow composite locations or non-global address\r
-space memory locations. Both these are needed in optimized code for devices with\r
-vector registers and address spaces.\r
-\r
-Bit field offsets are only supported in a limited way for register locations.\r
-Supporting them in a uniform manner for all location kinds is required to\r
-support languages with bit sized entities.\r
-\r
-# 4. Extension Solution\r
-\r
-This section outlines the extension to generalize the DWARF expression evaluation\r
-model to allow location descriptions to be manipulated on the stack. It presents\r
-a number of simplified examples to demonstrate the benefits and how the extension\r
-solves the issues of heterogeneous devices. It presents how this is done in\r
-a manner that is backwards compatible with DWARF 5.\r
-\r
-## 4.1 Location Description\r
-\r
-In order to have consistent, composable operations that act on location\r
-descriptions, the extension defines a uniform way to handle all location kinds.\r
-That includes memory, register, implicit, implicit pointer, undefined, and\r
-composite location descriptions.\r
-\r
-Each kind of location description is conceptually a zero-based offset within a\r
-piece of storage. The storage is a contiguous linear organization of a certain\r
-number of bytes (see below for how this is extended to support bit sized\r
-storage).\r
-\r
-- For global memory, the storage is the linear stream of bytes of the\r
- architecture's address size.\r
-- For each separate architecture register, it is the linear stream of bytes of\r
- the size of that specific register.\r
-- For an implicit, it is the linear stream of bytes of the value when\r
- represented using the value's base type which specifies the encoding, size,\r
- and byte ordering.\r
-- For undefined, it is an infinitely sized linear stream where every byte is\r
- undefined.\r
-- For composite, it is a linear stream of bytes defined by the composite's parts.\r
-\r
-## 4.2 Stack Location Description Operations\r
-\r
-The DWARF expression stack is extended to allow each stack entry to either be a\r
-value or a location description.\r
-\r
-Evaluation rules are defined to implicitly convert a stack element that is a\r
-value to a location description, or vice versa, so that all DWARF 5 expressions\r
-continue to have the same semantics. This reflects that a memory address is\r
-effectively used as a proxy for a memory location description.\r
-\r
-For each place that allows a DWARF expression to be specified, it is defined if\r
-the expression is to be evaluated as a value or a location description.\r
-\r
-Existing DWARF expression operations that are used to act on memory addresses\r
-are generalized to act on any location description kind. For example, the\r
-DW_OP_deref operation pops a location description rather than a memory address\r
-value from the stack and reads the storage associated with the location kind\r
-starting at the location description's offset.\r
-\r
-Existing DWARF expression operations that create location descriptions are\r
-changed to pop and push location descriptions on the stack. For example, the\r
-DW_OP_value, DW_OP_regx, DW_OP_implicit_value, DW_OP_implicit_pointer,\r
-DW_OP_stack_value, and DW_OP_piece.\r
-\r
-New operations that act on location descriptions can be added. For example, a\r
-DW_OP_offset operation that modifies the offset of the location description on\r
-top of the stack. Unlike the DW_OP_plus operation that only works with memory\r
-address, a DW_OP_offset operation can work with any location kind.\r
-\r
-To allow incremental and nested creation of composite location descriptions, a\r
-DW_OP_piece_end can be defined to explicitly indicate the last part of a\r
-composite. Currently, creating a composite must always be the last operation of\r
-an expression.\r
-\r
-A DW_OP_undefined operation can be defined that explicitly creates the undefined\r
-location description. Currently this is only possible as a piece of a composite\r
-when the stack is empty.\r
-\r
-## 4.3 Examples\r
-\r
-This section provides some motivating examples to illustrate the benefits that\r
-result from allowing location descriptions on the stack.\r
-\r
-### 4.3.1 Source Language Variable Spilled to Part of a Vector Register\r
-\r
-A compiler generating code for a GPU may allocate a source language variable\r
-that it proves has the same value for every lane of a SIMT thread in a scalar\r
-register. It may then need to spill that scalar register. To avoid the high cost\r
-of spilling to memory, it may spill to a fixed lane of one of the numerous\r
-vector registers.\r
-\r
-\r
-\r
-The following expression defines the location of a source language variable that\r
-the compiler allocated in a scalar register, but had to spill to lane 5 of a\r
-vector register at this point of the code.\r
-\r
- DW_OP_regx VGPR0\r
- DW_OP_offset_uconst 20\r
-\r
-\r
-\r
-The DW_OP_regx pushes a register location description on the stack. The storage\r
-for the register is the size of the vector register. The register location\r
-description conceptually references that storage with an initial offset of 0.\r
-The architecture defines the byte ordering of the register.\r
-\r
-\r
-\r
-The DW_OP_offset_uconst pops a location description off the stack, adds its\r
-operand value to the offset, and pushes the updated location description back on\r
-the stack. In this case the source language variable is being spilled to lane 5\r
-and each lane's component which is 32-bits (4 bytes), so the offset is 5*4=20.\r
-\r
-\r
-\r
-The result of the expression evaluation is the location description on the top\r
-of the stack.\r
-\r
-An alternative approach could be for the target to define distinct register\r
-names for each part of each vector register. However, this is not practical for\r
-GPUs due to the sheer number of registers that would have to be defined. It\r
-would also not permit a runtime index into part of the whole register to be used\r
-as shown in the next example.\r
-\r
-### 4.3.2 Source Language Variable Spread Across Multiple Vector Registers\r
-\r
-A compiler may generate SIMT code for a GPU. Each source language thread of\r
-execution is mapped to a single lane of the GPU thread. Source language\r
-variables that are mapped to a register, are mapped to the lane component of the\r
-vector registers corresponding to the source language's thread of execution.\r
-\r
-The location expression for such variables must therefore be executed in the\r
-context of the focused source language thread of execution. A DW_OP_push_lane\r
-operation can be defined to push the value of the lane for the currently focused\r
-source language thread of execution. The value to use would be provided by the\r
-consumer of DWARF when it evaluates the location expression.\r
-\r
-If the source language variable is larger than the size of the vector register\r
-lane component, then multiple vector registers are used. Each source language\r
-thread of execution will only use the vector register components for its\r
-associated lane.\r
-\r
-\r
-\r
-The following expression defines the location of a source language variable that\r
-has to occupy two vector registers. A composite location description is created\r
-that combines the two parts. It will give the correct result regardless of which\r
-lane corresponds to the source language thread of execution that the user is\r
-focused on.\r
-\r
- DW_OP_regx VGPR0\r
- DW_OP_push_lane\r
- DW_OP_uconst 4\r
- DW_OP_mul\r
- DW_OP_offset\r
- DW_OP_piece 4\r
- DW_OP_regx VGPR1\r
- DW_OP_push_lane\r
- DW_OP_uconst 4\r
- DW_OP_mul\r
- DW_OP_offset\r
- DW_OP_piece 4\r
-\r
-\r
-\r
-The DW_OP_regx VGPR0 pushes a location description for the first register.\r
-\r
-\r
-\r
-The DW_OP_push_lane; DW_OP_uconst 4; DW_OP_mul calculates the offset for the\r
-focused lanes vector register component as 4 times the lane number.\r
-\r
-\r
-\r
-\r
-\r
-\r
-\r
-The DW_OP_offset adjusts the register location description's offset to the\r
-runtime computed value.\r
-\r
-\r
-\r
-The DW_OP_piece either creates a new composite location description, or adds a\r
-new part to an existing incomplete one. It pops the location description to use\r
-for the new part. It then pops the next stack element if it is an incomplete\r
-composite location description, otherwise it creates a new incomplete composite\r
-location description with no parts. Finally it pushes the incomplete composite\r
-after adding the new part.\r
-\r
-In this case a register location description is added to a new incomplete\r
-composite location description. The 4 of the DW_OP_piece specifies the size of\r
-the register storage that comprises the part. Note that the 4 bytes start at the\r
-computed register offset.\r
-\r
-For backwards compatibility, if the stack is empty or the top stack element is\r
-an incomplete composite, an undefined location description is used for the part.\r
-If the top stack element is a generic base type value, then it is implicitly\r
-converted to a global memory location description with an offset equal to the\r
-value.\r
-\r
-\r
-\r
-The rest of the expression does the same for VGPR1. However, when the\r
-DW_OP_piece is evaluated there is an incomplete composite on the stack. So the\r
-VGPR1 register location description is added as a second part.\r
-\r
-\r
-\r
-\r
-\r
-\r
-\r
-\r
-\r
-\r
-\r
-\r
-\r
-At the end of the expression, if the top stack element is an incomplete\r
-composite location description, it is converted to a complete location\r
-description and returned as the result.\r
-\r
-\r
-\r
-### 4.3.3 Source Language Variable Spread Across Multiple Kinds of Locations\r
-\r
-This example is the same as the previous one, except the first 2 bytes of the\r
-second vector register have been spilled to memory, and the last 2 bytes have\r
-been proven to be a constant and optimized away.\r
-\r
-\r
-\r
- DW_OP_regx VGPR0\r
- DW_OP_push_lane\r
- DW_OP_uconst 4\r
- DW_OP_mul\r
- DW_OP_offset\r
- DW_OP_piece 4\r
- DW_OP_addr 0xbeef\r
- DW_OP_piece 2\r
- DW_OP_uconst 0xf00d\r
- DW_OP_stack_value\r
- DW_OP_piece 2\r
- DW_OP_piece_end\r
-\r
-The first 6 operations are the same.\r
-\r
-\r
-\r
-The DW_OP_addr operation pushes a global memory location description on the\r
-stack with an offset equal to the address.\r
-\r
-\r
-\r
-The next DW_OP_piece adds the global memory location description as the next 2\r
-byte part of the composite.\r
-\r
-\r
-\r
-The DW_OP_uconst 0xf00d; DW_OP_stack_value pushes an implicit location\r
-description on the stack. The storage of the implicit location description is\r
-the representation of the value 0xf00d using the generic base type's encoding,\r
-size, and byte ordering.\r
-\r
-\r
-\r
-\r
-\r
-The final DW_OP_piece adds 2 bytes of the implicit location description as the\r
-third part of the composite location description.\r
-\r
-\r
-\r
-The DW_OP_piece_end operation explicitly makes the incomplete composite location\r
-description into a complete location description. This allows a complete\r
-composite location description to be created on the stack that can be used as\r
-the location description of another following operation. For example, the\r
-DW_OP_offset can be applied to it. More practically, it permits creation of\r
-multiple composite location descriptions on the stack which can be used to pass\r
-arguments to a DWARF procedure using a DW_OP_call* operation. This can be\r
-beneficial to factor the incrementally creation of location descriptions.\r
-\r
-\r
-\r
-### 4.3.4 Address Spaces\r
-\r
-Heterogeneous devices can have multiple hardware supported address spaces which\r
-use specific hardware instructions to access them.\r
-\r
-For example, GPUs that use SIMT execution may provide hardware support to access\r
-memory such that each lane can see a linear memory view, while the backing\r
-memory is actually being accessed in an interleaved manner so that the locations\r
-for each lanes Nth dword are contiguous. This minimizes cache lines read by the\r
-SIMT execution.\r
-\r
-\r
-\r
-The following expression defines the location of a source language variable that\r
-is allocated at offset 0x10 in the current subprograms stack frame. The\r
-subprogram stack frames are per lane and reside in an interleaved address space.\r
-\r
- DW_OP_regval_type SGPR0 Generic\r
- DW_OP_uconst 1\r
- DW_OP_form_aspace_address\r
- DW_OP_offset 0x10\r
-\r
-\r
-\r
-The DW_OP_regval_type operation pushes the contents of SGPR0 as a generic value.\r
-This is the register that holds the address of the current stack frame.\r
-\r
-\r
-\r
-The DW_OP_uconst operation pushes the address space number. Each architecture\r
-defines the numbers it uses in DWARF. In this case, address space 1 is being\r
-used as the per lane memory.\r
-\r
-\r
-\r
-The DW_OP_form_aspace_address operation pops a value and an address space\r
-number. Each address space is associated with a separate storage. A memory\r
-location description is pushed which refers to the address space's storage, with\r
-an offset of the popped value.\r
-\r
-\r
-\r
-All operations that act on location descriptions work with memory locations\r
-regardless of their address space.\r
-\r
-Every architecture defines address space 0 as the default global memory address\r
-space.\r
-\r
-Generalizing memory location descriptions to include an address space component\r
-avoids having to create specialized operations to work with address spaces.\r
-\r
-The source variable is at offset 0x10 in the stack frame. The DW_OP_offset\r
-operation works on memory location descriptions that have an address space just\r
-like for any other kind of location description.\r
-\r
-\r
-\r
-The only operations in DWARF 5 that take an address space are DW_OP_xderef*.\r
-They treat a value as the address in a specified address space, and read its\r
-contents. There is no operation to actually create a location description that\r
-references an address space. There is no way to include address space memory\r
-locations in parts of composite locations.\r
-\r
-Since DW_OP_piece now takes any kind of location description for its pieces, it\r
-is now possible for parts of a composite to involve locations in different\r
-address spaces. For example, this can happen when parts of a source variable\r
-allocated in a register are spilled to a stack frame that resides in the\r
-non-global address space.\r
-\r
-### 4.3.5 Bit Offsets\r
-\r
-With the generalization of location descriptions on the stack, it is possible to\r
-define a DW_OP_bit_offset operation that adjusts the offset of any kind of\r
-location in terms of bits rather than bytes. The offset can be a runtime\r
-computed value. This is generally useful for any source language that support\r
-bit sized entities, and for registers that are not a whole number of bytes.\r
-\r
-DWARF 5 only supports bit fields in composites using DW_OP_bit_piece. It does\r
-not support runtime computed offsets which can happen for bit field packed\r
-arrays. It is also not generally composable as it must be the last part of an\r
-expression.\r
-\r
-The following example defines a location description for a source variable that\r
-is allocated starting at bit 20 of a register. A similar expression could be\r
-used if the source variable was at a bit offset within memory or a particular\r
-address space, or if the offset is a runtime value.\r
-\r
-\r
-\r
- DW_OP_regx SGPR3\r
- DW_OP_uconst 20\r
- DW_OP_bit_offset\r
-\r
-\r
-\r
-\r
-\r
-\r
-\r
-The DW_OP_bit_offset operation pops a value and location description from the\r
-stack. It pushes the location description after updating its offset using the\r
-value as a bit count.\r
-\r
-\r
-\r
-The ordering of bits within a byte, like byte ordering, is defined by the target\r
-architecture. A base type could be extended to specify bit ordering in addition\r
-to byte ordering.\r
-\r
-## 4.4 Call Frame Information (CFI)\r
-\r
-DWARF defines call frame information (CFI) that can be used to virtually unwind\r
-the subprogram call stack. This involves determining the location where register\r
-values have been spilled. DWARF 5 limits these locations to either be registers\r
-or global memory. As shown in the earlier examples, heterogeneous devices may\r
-spill registers to parts of other registers, to non-global memory address\r
-spaces, or even a composite of different location kinds.\r
-\r
-Therefore, the extension extends the CFI rules to support any kind of location\r
-description, and operations to create locations in address spaces.\r
-\r
-## 4.5 Objects Not In Byte Aligned Global Memory\r
-\r
-DWARF 5 only effectively supports byte aligned memory locations on the stack by\r
-using a global memory address as a proxy for a memory location description. This\r
-is a problem for attributes that define DWARF expressions that require the\r
-location of some source language entity that is not allocated in byte aligned\r
-global memory.\r
-\r
-For example, the DWARF expression of the DW_AT_data_member_location attribute is\r
-evaluated with an initial stack containing the location of a type instance\r
-object. That object could be located in a register, in a non-global memory\r
-address space, be described by a composite location description, or could even\r
-be an implicit location description.\r
-\r
-A similar problem exists for DWARF expressions that use the\r
-DW_OP_push_object_address operation. This operation pushes the location of a\r
-program object associated with the attribute that defines the expression.\r
-\r
-Allowing any kind of location description on the stack permits the DW_OP_call*\r
-operations to be used to factor the creation of location descriptions. The\r
-inputs and outputs of the call are passed on the stack. For example, on GPUs an\r
-expression can be defined to describe the effective PC of inactive lanes of SIMT\r
-execution. This is naturally done by composing the result of expressions for\r
-each nested control flow region. This can be done by making each control flow\r
-region have its own DWARF procedure, and then calling it from the expressions of\r
-the nested control flow regions. The alternative is to make each control flow\r
-region have the complete expression which results in much larger DWARF and is\r
-less convenient to generate.\r
-\r
-GPU compilers work hard to allocate objects in the larger number of registers to\r
-reduce memory accesses, they have to use different memory address spaces, and\r
-they perform optimizations that result in composites of these. Allowing\r
-operations to work with any kind of location description enables creating\r
-expressions that support all of these.\r
-\r
-Full general support for bit fields and implicit locations benefits\r
-optimizations on any target.\r
-\r
-## 4.6 Higher Order Operations\r
-\r
-The generalization allows an elegant way to add higher order operations that\r
-create location descriptions out of other location descriptions in a general\r
-composable manner.\r
-\r
-For example, a DW_OP_extend operation could create a composite location\r
-description out of a location description, an element size, and an element\r
-count. The resulting composite would effectively be a vector of element count\r
-elements with each element being the same location description of the specified\r
-bit size.\r
-\r
-A DW_OP_select_bit_piece operation could create a composite location description\r
-out of two location descriptions, a bit mask value, and an element size. The\r
-resulting composite would effectively be a vector of elements, selecting from\r
-one of the two input locations according to the bit mask.\r
-\r
-These could be used in the expression of an attribute that computes the\r
-effective PC of lanes of SIMT execution. The vector result efficiently computes\r
-the PC for each SIMT lane at once. The mask could be the hardware execution mask\r
-register that controls which SIMT lanes are executing. For active divergent\r
-lanes the vector element would be the current PC, and for inactive divergent\r
-lanes the PC would correspond to the source language line at which the lane is\r
-logically positioned.\r
-\r
-Similarly, a DW_OP_overlay_piece operation could be defined that creates a\r
-composite location description out of two location descriptions, an offset\r
-value, and a size. The resulting composite would consist of parts that are\r
-equivalent to one of the location descriptions, but with the other location\r
-description replacing a slice defined by the offset and size. This could be used\r
-to efficiently express a source language array that has had a set of elements\r
-promoted into a vector register when executing a set of iterations of a loop in\r
-a SIMD manner.\r
-\r
-## 4.7 Objects In Multiple Places\r
-\r
-A compiler may allocate a source variable in stack frame memory, but for some\r
-range of code may promote it to a register. If the generated code does not\r
-change the register value, then there is no need to save it back to memory.\r
-Effectively, during that range, the source variable is in both memory and a\r
-register. If a consumer, such as a debugger, allows the user to change the value\r
-of the source variable in that PC range, then it would need to change both\r
-places.\r
-\r
-DWARF 5 supports loclists which are able to specify the location of a source\r
-language entity is in different places at different PC locations. It can also\r
-express that a source language entity is in multiple places at the same time.\r
-\r
-DWARF 5 defines operation expressions and loclists separately. In general, this\r
-is adequate as non-memory location descriptions can only be computed as the last\r
-step of an expression evaluation.\r
-\r
-However, allowing location descriptions on the stack permits non-memory location\r
-descriptions to be used in the middle of expression evaluation. For example, the\r
-DW_OP_call* and DW_OP_implicit_pointer operations can result in evaluating the\r
-expression of a DW_AT_location attribute of a DIE. The DW_AT_location attribute\r
-allows the loclist form. So the result could include multiple location\r
-descriptions.\r
-\r
-Similarly, the DWARF expression associated with attributes such as\r
-DW_AT_data_member_location that are evaluated with an initial stack containing a\r
-location description, or a DWARF operation expression that uses the\r
-DW_OP_push_object_address operation, may want to act on the result of another\r
-expression that returned a location description involving multiple places.\r
-\r
-Therefore, the extension needs to define how expression operations that use those\r
-results will behave. The extension does this by generalizing the expression stack\r
-to allow an entry to be one or more single location descriptions. In doing this,\r
-it unifies the definitions of DWARF operation expressions and loclist\r
-expressions in a natural way.\r
-\r
-All operations that act on location descriptions are extended to act on multiple\r
-single location descriptions. For example, the DW_OP_offset operation adds the\r
-offset to each single location description. The DW_OP_deref* operations simply\r
-read the storage of one of the single location descriptions, since multiple\r
-single location descriptions must all hold the same value. Similarly, if the\r
-evaluation of a DWARF expression results in multiple single location\r
-descriptions, the consumer can ensure any updates are done to all of them, and\r
-any reads can use any one of them.\r
-\r
-# 5. Conclusion\r
-\r
-A strength of DWARF is that it has generally sought to provide generalized\r
-composable solutions that address many problems, rather than solutions that only\r
-address one-off issues. This extension attempts to follow that tradition by\r
-defining a backwards compatible composable generalization that can address a\r
-significant family of issues. It addresses the specific issues present for\r
-heterogeneous computing devices, provides benefits for non-heterogeneous\r
-devices, and can help address a number of other previously reported issues.\r
-\r
-# A. Changes to DWARF Debugging Information Format Version 5\r
-\r
-> NOTE: This appendix provides changes relative to DWARF Version 5. It has been\r
-> defined such that it is backwards compatible with DWARF Version 5.\r
-> Non-normative text is shown in <i>italics</i>. The section numbers generally\r
-> correspond to those in the DWARF Version 5 standard unless specified\r
-> otherwise. Definitions are given to clarify how existing expression\r
-> operations, CFI operations, and attributes behave with respect to generalized\r
-> location descriptions that support multiple places.\r
->\r
-> > NOTE: Notes are included to describe how the changes are to be applied to\r
-> > the DWARF Version 5 standard. They also describe rational and issues that\r
-> > may need further consideration.\r
-\r
-## A.2 General Description\r
-\r
-### A.2.5 DWARF Expressions\r
-\r
-> NOTE: This section, and its nested sections, replaces DWARF Version 5 section\r
-> 2.5 and section 2.6. It is based on the text of the existing DWARF Version 5\r
-> standard.\r
-\r
-DWARF expressions describe how to compute a value or specify a location.\r
-\r
-<i>The evaluation of a DWARF expression can provide the location of an object,\r
-the value of an array bound, the length of a dynamic string, the desired value\r
-itself, and so on.</i>\r
-\r
-If the evaluation of a DWARF expression does not encounter an error, then it can\r
-either result in a value (see [2.5.2 DWARF Expression\r
-Value](#dwarf-expression-value)) or a location description (see [2.5.3 DWARF\r
-Location Description](#dwarf-location-description)). When a DWARF expression\r
-is evaluated, it may be specified whether a value or location description is\r
-required as the result kind.\r
-\r
-If a result kind is specified, and the result of the evaluation does not match\r
-the specified result kind, then the implicit conversions described in [2.5.4.4.3\r
-Memory Location Description\r
-Operations](#memory-location-description-operations) are performed if\r
-valid. Otherwise, the DWARF expression is ill-formed.\r
-\r
-If the evaluation of a DWARF expression encounters an evaluation error, then the\r
-result is an evaluation error.\r
-\r
-> NOTE: Decided to define the concept of an evaluation error. An alternative is\r
-> to introduce an undefined value base type in a similar way to location\r
-> descriptions having an undefined location description. Then operations that\r
-> encounter an evaluation error can return the undefined location description or\r
-> value with an undefined base type.\r
->\r
-> All operations that act on values would return an undefined entity if given an\r
-> undefined value. The expression would then always evaluate to completion, and\r
-> can be tested to determine if it is an undefined entity.\r
->\r
-> However, this would add considerable additional complexity and does not match\r
-> that GDB throws an exception when these evaluation errors occur.\r
-\r
-If a DWARF expression is ill-formed, then the result is undefined.\r
-\r
-The following sections detail the rules for when a DWARF expression is\r
-ill-formed or results in an evaluation error.\r
-\r
-A DWARF expression can either be encoded as an operation expression (see [2.5.4\r
-DWARF Operation Expressions](#dwarf-operation-expressions)), or as a\r
-location list expression (see [2.5.5 DWARF Location List\r
-Expressions](#dwarf-location-list-expressions)).\r
-\r
-#### A.2.5.1 DWARF Expression Evaluation Context\r
-\r
-A DWARF expression is evaluated in a context that can include a number of\r
-context elements. If multiple context elements are specified then they must be\r
-self consistent or the result of the evaluation is undefined. The context\r
-elements that can be specified are:\r
-\r
-1. <i>A current result kind</i>\r
-\r
- The kind of result required by the DWARF expression evaluation. If specified\r
- it can be a location description or a value.\r
-\r
-2. <i>A current thread</i>\r
-\r
- The target architecture thread identifier of the source program thread of\r
- execution for which a user presented expression is currently being\r
- evaluated.\r
-\r
- It is required for operations that are related to target architecture\r
- threads.\r
-\r
- <i>For example, the `DW_OP_regval_type` operation.</i>\r
-\r
-3. <i>A current call frame</i>\r
-\r
- The target architecture call frame identifier. It identifies a call frame\r
- that corresponds to an active invocation of a subprogram in the current\r
- thread. It is identified by its address on the call stack. The address is\r
- referred to as the Canonical Frame Address (CFA). The call frame information\r
- is used to determine the CFA for the call frames of the current thread's\r
- call stack (see [6.4 Call Frame Information](#call-frame-information)).\r
-\r
- It is required for operations that specify target architecture registers to\r
- support virtual unwinding of the call stack.\r
-\r
- <i>For example, the `DW_OP_*reg*` operations.</i>\r
-\r
- If specified, it must be an active call frame in the current thread.\r
- Otherwise the result is undefined.\r
-\r
- If it is the currently executing call frame, then it is termed the top call\r
- frame.\r
-\r
-4. <i>A current program location</i>\r
-\r
- The target architecture program location corresponding to the current call\r
- frame of the current thread.\r
-\r
- The program location of the top call frame is the target architecture\r
- program counter for the current thread. The call frame information is used\r
- to obtain the value of the return address register to determine the program\r
- location of the other call frames (see [6.4 Call Frame\r
- Information](#call-frame-information)).\r
-\r
- It is required for the evaluation of location list expressions to select\r
- amongst multiple program location ranges. It is required for operations that\r
- specify target architecture registers to support virtual unwinding of the\r
- call stack (see [6.4 Call Frame Information](#call-frame-information)).\r
-\r
- If specified:\r
-\r
- - If the current call frame is the top call frame, it must be the current\r
- target architecture program location.\r
- - If the current call frame F is not the top call frame, it must be the\r
- program location associated with the call site in the current caller frame\r
- F that invoked the callee frame.\r
- - Otherwise the result is undefined.\r
-\r
-5. <i>A current compilation unit</i>\r
-\r
- The compilation unit debug information entry that contains the DWARF\r
- expression being evaluated.\r
-\r
- It is required for operations that reference debug information associated\r
- with the same compilation unit, including indicating if such references use\r
- the 32-bit or 64-bit DWARF format. It can also provide the default address\r
- space address size if no current target architecture is specified.\r
-\r
- <i>For example, the `DW_OP_constx` and `DW_OP_addrx` operations.</i>\r
-\r
- <i>Note that this compilation unit may not be the same as the compilation\r
- unit determined from the loaded code object corresponding to the current\r
- program location. For example, the evaluation of the expression E associated\r
- with a `DW_AT_location` attribute of the debug information entry operand of\r
- the `DW_OP_call*` operations is evaluated with the compilation unit that\r
- contains E and not the one that contains the `DW_OP_call*` operation\r
- expression.</i>\r
-\r
-6. <i>A current target architecture</i>\r
-\r
- The target architecture.\r
-\r
- It is required for operations that specify target architecture specific\r
- entities.\r
-\r
- <i>For example, target architecture specific entities include DWARF register\r
- identifiers, DWARF address space identifiers, the default address space, and\r
- the address space address sizes.</i>\r
-\r
- If specified:\r
-\r
- - If the current thread is specified, then the current target architecture\r
- must be the same as the target architecture of the current thread.\r
- - If the current compilation unit is specified, then the current target\r
- architecture default address space address size must be the same as the\r
- `address_size` field in the header of the current compilation unit and any\r
- associated entry in the `.debug_aranges` section.\r
- - If the current program location is specified, then the current target\r
- architecture must be the same as the target architecture of any line\r
- number information entry (see [6.2 Line Number\r
- Information](#line-number-information)) corresponding to the current\r
- program location.\r
- - If the current program location is specified, then the current target\r
- architecture default address space address size must be the same as the\r
- `address_size` field in the header of any entry corresponding to the\r
- current program location in the `.debug_addr`, `.debug_line`,\r
- `.debug_rnglists`, `.debug_rnglists.dwo`, `.debug_loclists`, and\r
- `.debug_loclists.dwo` sections.\r
- - Otherwise the result is undefined.\r
-\r
-7. <i>A current object</i>\r
-\r
- The location description of a program object.\r
-\r
- It is required for the `DW_OP_push_object_address` operation.\r
-\r
- <i>For example, the `DW_AT_data_location` attribute on type debug\r
- information entries specifies the program object corresponding to a runtime\r
- descriptor as the current object when it evaluates its associated\r
- expression.</i>\r
-\r
- The result is undefined if the location descriptor is invalid (see [3.5.3\r
- DWARF Location Description](#dwarf-location-description)).\r
-\r
-8. <i>An initial stack</i>\r
-\r
- This is a list of values or location descriptions that will be pushed on the\r
- operation expression evaluation stack in the order provided before\r
- evaluation of an operation expression starts.\r
-\r
- Some debugger information entries have attributes that evaluate their DWARF\r
- expression value with initial stack entries. In all other cases the initial\r
- stack is empty.\r
-\r
- The result is undefined if any location descriptors are invalid (see [3.5.3\r
- DWARF Location Description](#dwarf-location-description)).\r
-\r
-If the evaluation requires a context element that is not specified, then the\r
-result of the evaluation is an error.\r
-\r
-<i>A DWARF expression for a location description may be able to be evaluated\r
-without a thread, call frame, program location, or architecture context. For\r
-example, the location of a global variable may be able to be evaluated without\r
-such context. If the expression evaluates with an error then it may indicate the\r
-variable has been optimized and so requires more context.</i>\r
-\r
-<i>The DWARF expression for call frame information (see [6.4 Call Frame\r
-Information](#call-frame-information)) operations are restricted to those\r
-that do not require the compilation unit context to be specified.</i>\r
-\r
-The DWARF is ill-formed if all the `address_size` fields in the headers of all\r
-the entries in the `.debug_info`, `.debug_addr`, `.debug_line`,\r
-`.debug_rnglists`, `.debug_rnglists.dwo`, `.debug_loclists`, and\r
-`.debug_loclists.dwo` sections corresponding to any given program location do\r
-not match.\r
-\r
-#### A.2.5.2 DWARF Expression Value\r
-\r
-A value has a type and a literal value. It can represent a literal value of any\r
-supported base type of the target architecture. The base type specifies the\r
-size, encoding, and endianity of the literal value.\r
-\r
-> NOTE: It may be desirable to add an implicit pointer base type encoding. It\r
-> would be used for the type of the value that is produced when the\r
-> `DW_OP_deref*` operation retrieves the full contents of an implicit pointer\r
-> location storage created by the `DW_OP_implicit_pointer` operation. The\r
-> literal value would record the debugging information entry and byte\r
-> displacement specified by the associated `DW_OP_implicit_pointer` operation.\r
-\r
-There is a distinguished base type termed the generic type, which is an integral\r
-type that has the size of an address in the target architecture default address\r
-space, a target architecture defined endianity, and unspecified signedness.\r
-\r
-<i>The generic type is the same as the unspecified type used for stack\r
-operations defined in DWARF Version 4 and before.</i>\r
-\r
-An integral type is a base type that has an encoding of `DW_ATE_signed`,\r
-`DW_ATE_signed_char`, `DW_ATE_unsigned`, `DW_ATE_unsigned_char`,\r
-`DW_ATE_boolean`, or any target architecture defined integral encoding in the\r
-inclusive range `DW_ATE_lo_user` to `DW_ATE_hi_user`.\r
-\r
-> NOTE: It is unclear if `DW_ATE_address` is an integral type. GDB does not seem\r
-> to consider it as integral.\r
-\r
-#### A.2.5.3 DWARF Location Description\r
-\r
-<i>Debugging information must provide consumers a way to find the location of\r
-program variables, determine the bounds of dynamic arrays and strings, and\r
-possibly to find the base address of a subprogram's call frame or the return\r
-address of a subprogram. Furthermore, to meet the needs of recent computer\r
-architectures and optimization techniques, debugging information must be able to\r
-describe the location of an object whose location changes over the object's\r
-lifetime, and may reside at multiple locations simultaneously during parts of an\r
-object's lifetime.</i>\r
-\r
-Information about the location of program objects is provided by location\r
-descriptions.\r
-\r
-Location descriptions can consist of one or more single location descriptions.\r
-\r
-A single location description specifies the location storage that holds a\r
-program object and a position within the location storage where the program\r
-object starts. The position within the location storage is expressed as a bit\r
-offset relative to the start of the location storage.\r
-\r
-A location storage is a linear stream of bits that can hold values. Each\r
-location storage has a size in bits and can be accessed using a zero-based bit\r
-offset. The ordering of bits within a location storage uses the bit numbering\r
-and direction conventions that are appropriate to the current language on the\r
-target architecture.\r
-\r
-There are five kinds of location storage:\r
-\r
-1. <i>memory location storage</i>\r
-\r
- Corresponds to the target architecture memory address spaces.\r
-\r
-2. <i>register location storage</i>\r
-\r
- Corresponds to the target architecture registers.\r
-\r
-3. <i>implicit location storage</i>\r
-\r
- Corresponds to fixed values that can only be read.\r
-\r
-4. <i>undefined location storage</i>\r
-\r
- Indicates no value is available and therefore cannot be read or written.\r
-\r
-5. <i>composite location storage</i>\r
-\r
- Allows a mixture of these where some bits come from one location storage and\r
- some from another location storage, or from disjoint parts of the same\r
- location storage.\r
-\r
-> NOTE: It may be better to add an implicit pointer location storage kind used\r
-> by the `DW_OP_implicit_pointer` operation. It would specify the debugger\r
-> information entry and byte offset provided by the operations.\r
-\r
-<i>Location descriptions are a language independent representation of addressing\r
-rules.</i>\r
-\r
-- <i>They can be the result of evaluating a debugger information entry attribute\r
- that specifies an operation expression of arbitrary complexity. In this usage\r
- they can describe the location of an object as long as its lifetime is either\r
- static or the same as the lexical block (see [3.5 Lexical Block\r
- Entries](#lexical-block-entries)) that owns it, and it does not move during\r
- its lifetime.</i>\r
-\r
-- <i>They can be the result of evaluating a debugger information entry attribute\r
- that specifies a location list expression. In this usage they can describe the\r
- location of an object that has a limited lifetime, changes its location during\r
- its lifetime, or has multiple locations over part or all of its lifetime.</i>\r
-\r
-If a location description has more than one single location description, the\r
-DWARF expression is ill-formed if the object value held in each single location\r
-description's position within the associated location storage is not the same\r
-value, except for the parts of the value that are uninitialized.\r
-\r
-<i>A location description that has more than one single location description can\r
-only be created by a location list expression that has overlapping program\r
-location ranges, or certain expression operations that act on a location\r
-description that has more than one single location description. There are no\r
-operation expression operations that can directly create a location description\r
-with more than one single location description.</i>\r
-\r
-<i>A location description with more than one single location description can be\r
-used to describe objects that reside in more than one piece of storage at the\r
-same time. An object may have more than one location as a result of\r
-optimization. For example, a value that is only read may be promoted from memory\r
-to a register for some region of code, but later code may revert to reading the\r
-value from memory as the register may be used for other purposes. For the code\r
-region where the value is in a register, any change to the object value must be\r
-made in both the register and the memory so both regions of code will read the\r
-updated value.</i>\r
-\r
-<i>A consumer of a location description with more than one single location\r
-description can read the object's value from any of the single location\r
-descriptions (since they all refer to location storage that has the same value),\r
-but must write any changed value to all the single location descriptions.</i>\r
-\r
-Updating a location description L by a bit offset B is defined as adding the\r
-value of B to the bit offset of each single location description SL of L. It is\r
-an evaluation error if the updated bit offset of any SL is less than 0 or\r
-greater than or equal to the size of the location storage specified by SL.\r
-\r
-The evaluation of an expression may require context elements to create a\r
-location description. If such a location description is accessed, the storage it\r
-denotes is that associated with the context element values specified when the\r
-location description was created, which may differ from the context at the time\r
-it is accessed.\r
-\r
-<i>For example, creating a register location description requires the thread\r
-context: the location storage is for the specified register of that thread.\r
-Creating a memory location description for an address space may required a\r
-thread context: the location storage is the memory associated with that\r
-thread.</i>\r
-\r
-If any of the context elements required to create a location description change,\r
-the location description becomes invalid and accessing it is undefined.\r
-\r
-<i>Examples of context that can invalidate a location description are:</i>\r
-\r
-- <i>The thread context is required and execution causes the thread to\r
- terminate.</i>\r
-- <i>The call frame context is required and further execution causes the call\r
- frame to return to the calling frame.</i>\r
-- <i>The program location is required and further execution of the thread\r
- occurs. That could change the location list entry or call frame information\r
- entry that applies.</i>\r
-- <i>An operation uses call frame information:</i>\r
- - <i>Any of the frames used in the virtual call frame unwinding return.</i>\r
- - <i>The top call frame is used, the program location is used to select the\r
- call frame information entry, and further execution of the thread\r
- occurs.</i>\r
-\r
-<i>A DWARF expression can be used to compute a location description for an\r
-object. A subsequent DWARF expression evaluation can be given the object\r
-location description as the object context or initial stack context to compute a\r
-component of the object. The final result is undefined if the object location\r
-description becomes invalid between the two expression evaluations.</i>\r
-\r
-A change of a thread's program location may not make a location description\r
-invalid, yet may still render it as no longer meaningful. Accessing such a\r
-location description, or using it as the object context or initial stack context\r
-of an expression evaluation, may produce an undefined result.\r
-\r
-<i>For example, a location description may specify a register that no longer\r
-holds the intended program object after a program location change. One way to\r
-avoid such problems is to recompute location descriptions associated with\r
-threads when their program locations change.</i>\r
-\r
-#### A.2.5.4 DWARF Operation Expressions\r
-\r
-An operation expression is comprised of a stream of operations, each consisting\r
-of an opcode followed by zero or more operands. The number of operands is\r
-implied by the opcode.\r
-\r
-Operations represent a postfix operation on a simple stack machine. Each stack\r
-entry can hold either a value or a location description. Operations can act on\r
-entries on the stack, including adding entries and removing entries. If the kind\r
-of a stack entry does not match the kind required by the operation and is not\r
-implicitly convertible to the required kind (see [2.5.4.4.3 Memory Location\r
-Description Operations](#memory-location-description-operations)), then\r
-the DWARF operation expression is ill-formed.\r
-\r
-Evaluation of an operation expression starts with an empty stack on which the\r
-entries from the initial stack provided by the context are pushed in the order\r
-provided. Then the operations are evaluated, starting with the first operation\r
-of the stream. Evaluation continues until either an operation has an evaluation\r
-error, or until one past the last operation of the stream is reached.\r
-\r
-The result of the evaluation is:\r
-\r
-- If an operation has an evaluation error, or an operation evaluates an\r
- expression that has an evaluation error, then the result is an evaluation\r
- error.\r
-- If the current result kind specifies a location description, then:\r
- - If the stack is empty, the result is a location description with one\r
- undefined location description.\r
-\r
- <i>This rule is for backwards compatibility with DWARF Version 5 which uses\r
- an empty operation expression for this purpose.</i>\r
-\r
- - If the top stack entry is a location description, or can be converted to one\r
- (see [2.5.4.4.3 Memory Location Description\r
- Operations](#memory-location-description-operations)), then the result\r
- is that, possibly converted, location description. Any other entries on the\r
- stack are discarded.\r
- - Otherwise the DWARF expression is ill-formed.\r
-\r
- > NOTE: Could define this case as returning an implicit location description\r
- > as if the `DW_OP_implicit` operation is performed.\r
-\r
-- If the current result kind specifies a value, then:\r
- - If the top stack entry is a value, or can be converted to one (see\r
- [2.5.4.4.3 Memory Location Description\r
- Operations](#memory-location-description-operations)), then the result is\r
- that, possibly converted, value. Any other entries on the stack are\r
- discarded.\r
- - Otherwise the DWARF expression is ill-formed.\r
-- If the current result kind is not specified, then:\r
- - If the stack is empty, the result is a location description with one\r
- undefined location description.\r
-\r
- <i>This rule is for backwards compatibility with DWARF Version 5 which uses\r
- an empty operation expression for this purpose.</i>\r
-\r
- > NOTE: This rule is consistent with the rule above for when a location\r
- > description is requested. However, GDB appears to report this as an error\r
- > and no GDB tests appear to cause an empty stack for this case.\r
-\r
- - Otherwise, the top stack entry is returned. Any other entries on the stack\r
- are discarded.\r
-\r
-An operation expression is encoded as a byte block with some form of prefix that\r
-specifies the byte count. It can be used:\r
-\r
-- as the value of a debugging information entry attribute that is encoded using\r
- class `exprloc` (see [7.5.5 Classes and Forms](#classes-and-forms)),\r
-- as the operand to certain operation expression operations,\r
-- as the operand to certain call frame information operations (see [6.4 Call\r
- Frame Information](#call-frame-information)),\r
-- and in location list entries (see [2.5.5 DWARF Location List\r
- Expressions](#dwarf-location-list-expressions)).\r
-\r
-##### A.2.5.4.1 Stack Operations\r
-\r
-> NOTE: This section replaces DWARF Version 5 section 2.5.1.3.\r
-\r
-The following operations manipulate the DWARF stack. Operations that index the\r
-stack assume that the top of the stack (most recently added entry) has index 0.\r
-They allow the stack entries to be either a value or location description.\r
-\r
-If any stack entry accessed by a stack operation is an incomplete composite\r
-location description (see [2.5.4.4.6 Composite Location Description\r
-Operations](#composite-location-description-operations)), then the DWARF\r
-expression is ill-formed.\r
-\r
-> NOTE: These operations now support stack entries that are values and location\r
-> descriptions.\r
-\r
-> NOTE: If it is desired to also make them work with incomplete composite\r
-> location descriptions, then would need to define that the composite location\r
-> storage specified by the incomplete composite location description is also\r
-> replicated when a copy is pushed. This ensures that each copy of the\r
-> incomplete composite location description can update the composite location\r
-> storage they specify independently.\r
-\r
-1. `DW_OP_dup`\r
-\r
- `DW_OP_dup` duplicates the stack entry at the top of the stack.\r
-\r
-2. `DW_OP_drop`\r
-\r
- `DW_OP_drop` pops the stack entry at the top of the stack and discards it.\r
-\r
-3. `DW_OP_pick`\r
-\r
- `DW_OP_pick` has a single unsigned 1-byte operand that represents an index\r
- I. A copy of the stack entry with index I is pushed onto the stack.\r
-\r
-4. `DW_OP_over`\r
-\r
- `DW_OP_over` pushes a copy of the entry with index 1.\r
-\r
- <i>This is equivalent to a `DW_OP_pick 1` operation.</i>\r
-\r
-5. `DW_OP_swap`\r
-\r
- `DW_OP_swap` swaps the top two stack entries. The entry at the top of the\r
- stack becomes the second stack entry, and the second stack entry becomes the\r
- top of the stack.\r
-\r
-6. `DW_OP_rot`\r
-\r
- `DW_OP_rot` rotates the first three stack entries. The entry at the top of\r
- the stack becomes the third stack entry, the second entry becomes the top of\r
- the stack, and the third entry becomes the second entry.\r
-\r
-##### A.2.5.4.2 Control Flow Operations\r
-\r
-> NOTE: This section replaces DWARF Version 5 section 2.5.1.5.\r
-\r
-The following operations provide simple control of the flow of a DWARF operation\r
-expression.\r
-\r
-1. `DW_OP_nop`\r
-\r
- `DW_OP_nop` is a place holder. It has no effect on the DWARF stack entries.\r
-\r
-2. `DW_OP_le`, `DW_OP_ge`, `DW_OP_eq`, `DW_OP_lt`, `DW_OP_gt`,\r
- `DW_OP_ne`\r
-\r
- > NOTE: The same as in DWARF Version 5 section 2.5.1.5.\r
-\r
-3. `DW_OP_skip`\r
-\r
- `DW_OP_skip` is an unconditional branch. Its single operand is a 2-byte\r
- signed integer constant. The 2-byte constant is the number of bytes of the\r
- DWARF expression to skip forward or backward from the current operation,\r
- beginning after the 2-byte constant.\r
-\r
- If the updated position is at one past the end of the last operation, then\r
- the operation expression evaluation is complete.\r
-\r
- Otherwise, the DWARF expression is ill-formed if the updated operation\r
- position is not in the range of the first to last operation inclusive, or\r
- not at the start of an operation.\r
-\r
-4. `DW_OP_bra`\r
-\r
- `DW_OP_bra` is a conditional branch. Its single operand is a 2-byte signed\r
- integer constant. This operation pops the top of stack. If the value popped\r
- is not the constant 0, the 2-byte constant operand is the number of bytes of\r
- the DWARF operation expression to skip forward or backward from the current\r
- operation, beginning after the 2-byte constant.\r
-\r
- If the updated position is at one past the end of the last operation, then\r
- the operation expression evaluation is complete.\r
-\r
- Otherwise, the DWARF expression is ill-formed if the updated operation\r
- position is not in the range of the first to last operation inclusive, or\r
- not at the start of an operation.\r
-\r
-5. `DW_OP_call2, DW_OP_call4, DW_OP_call_ref`\r
-\r
- `DW_OP_call2`, `DW_OP_call4`, and `DW_OP_call_ref` perform DWARF procedure\r
- calls during evaluation of a DWARF expression.\r
-\r
- `DW_OP_call2` and `DW_OP_call4`, have one operand that is, respectively, a\r
- 2-byte or 4-byte unsigned offset DR that represents the byte offset of a\r
- debugging information entry D relative to the beginning of the current\r
- compilation unit.\r
-\r
- `DW_OP_call_ref` has one operand that is a 4-byte unsigned value in the\r
- 32-bit DWARF format, or an 8-byte unsigned value in the 64-bit DWARF format,\r
- that represents the byte offset DR of a debugging information entry D\r
- relative to the beginning of the `.debug_info` section that contains the\r
- current compilation unit. D may not be in the current compilation unit.\r
-\r
- > NOTE: DWARF Version 5 states that DR can be an offset in a `.debug_info`\r
- > section other than the one that contains the current compilation unit. It\r
- > states that relocation of references from one executable or shared object\r
- > file to another must be performed by the consumer. But given that DR is\r
- > defined as an offset in a `.debug_info` section this seems impossible. If\r
- > DR was defined as an implementation defined value, then the consumer could\r
- > choose to interpret the value in an implementation defined manner to\r
- > reference a debug information in another executable or shared object.\r
- >\r
- > In ELF the `.debug_info` section is in a non-`PT_LOAD` segment so standard\r
- > dynamic relocations cannot be used. But even if they were loaded segments\r
- > and dynamic relocations were used, DR would need to be the address of D,\r
- > not an offset in a `.debug_info` section. That would also need DR to be\r
- > the size of a global address. So it would not be possible to use the\r
- > 32-bit DWARF format in a 64-bit global address space. In addition, the\r
- > consumer would need to determine what executable or shared object the\r
- > relocated address was in so it could determine the containing compilation\r
- > unit.\r
- >\r
- > GDB only interprets DR as an offset in the `.debug_info` section that\r
- > contains the current compilation unit.\r
- >\r
- > This comment also applies to `DW_OP_implicit_pointer`.\r
-\r
- <i>Operand interpretation of `DW_OP_call2`, `DW_OP_call4`, and\r
- `DW_OP_call_ref` is exactly like that for `DW_FORM_ref2`, `DW_FORM_ref4`,\r
- and `DW_FORM_ref_addr`, respectively.</i>\r
-\r
- The call operation is evaluated by:\r
-\r
- - If D has a `DW_AT_location` attribute that is encoded as a `exprloc` that\r
- specifies an operation expression E, then execution of the current\r
- operation expression continues from the first operation of E. Execution\r
- continues until one past the last operation of E is reached, at which\r
- point execution continues with the operation following the call operation.\r
- The operations of E are evaluated with the same current context, except\r
- current compilation unit is the one that contains D and the stack is the\r
- same as that being used by the call operation. After the call operation\r
- has been evaluated, the stack is therefore as it is left by the evaluation\r
- of the operations of E. Since E is evaluated on the same stack as the call\r
- operation, E can use, and/or remove entries already on the stack, and can\r
- add new entries to the stack.\r
-\r
- <i>Values on the stack at the time of the call may be used as parameters\r
- by the called expression and values left on the stack by the called\r
- expression may be used as return values by prior agreement between the\r
- calling and called expressions.</i>\r
-\r
- - If D has a `DW_AT_location` attribute that is encoded as a `loclist` or\r
- `loclistsptr`, then the specified location list expression E is evaluated.\r
- The evaluation of E uses the current context, except the result kind is a\r
- location description, the compilation unit is the one that contains D, and\r
- the initial stack is empty. The location description result is pushed on\r
- the stack.\r
-\r
- > NOTE: This rule avoids having to define how to execute a matched\r
- > location list entry operation expression on the same stack as the call\r
- > when there are multiple matches. But it allows the call to obtain the\r
- > location description for a variable or formal parameter which may use a\r
- > location list expression.\r
- >\r
- > An alternative is to treat the case when D has a `DW_AT_location`\r
- > attribute that is encoded as a `loclist` or `loclistsptr`, and the\r
- > specified location list expression E' matches a single location list\r
- > entry with operation expression E, the same as the `exprloc` case and\r
- > evaluate on the same stack.\r
- >\r
- > But this is not attractive as if the attribute is for a variable that\r
- > happens to end with a non-singleton stack, it will not simply put a\r
- > location description on the stack. Presumably the intent of using\r
- > `DW_OP_call*` on a variable or formal parameter debugger information\r
- > entry is to push just one location description on the stack. That\r
- > location description may have more than one single location description.\r
- >\r
- > The previous rule for `exprloc` also has the same problem, as normally a\r
- > variable or formal parameter location expression may leave multiple\r
- > entries on the stack and only return the top entry.\r
- >\r
- > GDB implements `DW_OP_call*` by always executing E on the same stack. If\r
- > the location list has multiple matching entries, it simply picks the\r
- > first one and ignores the rest. This seems fundamentally at odds with\r
- > the desire to support multiple places for variables.\r
- >\r
- > So, it feels like `DW_OP_call*` should both support pushing a location\r
- > description on the stack for a variable or formal parameter, and also\r
- > support being able to execute an operation expression on the same stack.\r
- > Being able to specify a different operation expression for different\r
- > program locations seems a desirable feature to retain.\r
- >\r
- > A solution to that is to have a distinct `DW_AT_proc` attribute for the\r
- > `DW_TAG_dwarf_procedure` debugging information entry. Then the\r
- > `DW_AT_location` attribute expression is always executed separately and\r
- > pushes a location description (that may have multiple single location\r
- > descriptions), and the `DW_AT_proc` attribute expression is always\r
- > executed on the same stack and can leave anything on the stack.\r
- >\r
- > The `DW_AT_proc` attribute could have the new classes `exprproc`,\r
- > `loclistproc`, and `loclistsptrproc` to indicate that the expression is\r
- > executed on the same stack. `exprproc` is the same encoding as\r
- > `exprloc`. `loclistproc` and `loclistsptrproc` are the same encoding as\r
- > their non-`proc` counterparts, except the DWARF is ill-formed if the\r
- > location list does not match exactly one location list entry and a\r
- > default entry is required. These forms indicate explicitly that the\r
- > matched single operation expression must be executed on the same stack.\r
- > This is better than ad hoc special rules for `loclistproc` and\r
- > `loclistsptrproc` which are currently clearly defined to always return a\r
- > location description. The producer then explicitly indicates the intent\r
- > through the attribute classes.\r
- >\r
- > Such a change would be a breaking change for how GDB implements\r
- > `DW_OP_call*`. However, are the breaking cases actually occurring in\r
- > practice? GDB could implement the current approach for DWARF Version 5,\r
- > and the new semantics for DWARF Version 6 which has been done for some\r
- > other features.\r
- >\r
- > Another option is to limit the execution to be on the same stack only to\r
- > the evaluation of an expression E that is the value of a\r
- > `DW_AT_location` attribute of a `DW_TAG_dwarf_procedure` debugging\r
- > information entry. The DWARF would be ill-formed if E is a location list\r
- > expression that does not match exactly one location list entry. In all\r
- > other cases the evaluation of an expression E that is the value of a\r
- > `DW_AT_location` attribute would evaluate E with the current context,\r
- > except the result kind is a location description, the compilation unit\r
- > is the one that contains D, and the initial stack is empty. The location\r
- > description result is pushed on the stack.\r
-\r
- - If D has a `DW_AT_const_value` attribute with a value V, then it is as if\r
- a `DW_OP_implicit_value V` operation was executed.\r
-\r
- <i>This allows a call operation to be used to compute the location\r
- description for any variable or formal parameter regardless of whether the\r
- producer has optimized it to a constant. This is consistent with the\r
- `DW_OP_implicit_pointer` operation.</i>\r
-\r
- > NOTE: Alternatively, could deprecate using `DW_AT_const_value` for\r
- > `DW_TAG_variable` and `DW_TAG_formal_parameter` debugger information\r
- > entries that are constants and instead use `DW_AT_location` with an\r
- > operation expression that results in a location description with one\r
- > implicit location description. Then this rule would not be required.\r
-\r
- - Otherwise, there is no effect and no changes are made to the stack.\r
-\r
- > NOTE: In DWARF Version 5, if D does not have a `DW_AT_location` then\r
- > `DW_OP_call*` is defined to have no effect. It is unclear that this is\r
- > the right definition as a producer should be able to rely on using\r
- > `DW_OP_call*` to get a location description for any\r
- > non-`DW_TAG_dwarf_procedure` debugging information entries. Also, the\r
- > producer should not be creating DWARF with `DW_OP_call*` to a\r
- > `DW_TAG_dwarf_procedure` that does not have a `DW_AT_location`\r
- > attribute. So, should this case be defined as an ill-formed DWARF\r
- > expression?\r
-\r
- <i>The `DW_TAG_dwarf_procedure` debugging information entry can be used to\r
- define DWARF procedures that can be called.</i>\r
-\r
-##### A.2.5.4.3 Value Operations\r
-\r
-This section describes the operations that push values on the stack.\r
-\r
-Each value stack entry has a type and a literal value. It can represent a\r
-literal value of any supported base type of the target architecture. The base\r
-type specifies the size, encoding, and endianity of the literal value.\r
-\r
-The base type of value stack entries can be the distinguished generic type.\r
-\r
-###### A.2.5.4.3.1 Literal Operations\r
-\r
-> NOTE: This section replaces DWARF Version 5 section 2.5.1.1.\r
-\r
-The following operations all push a literal value onto the DWARF stack.\r
-\r
-Operations other than `DW_OP_const_type` push a value V with the generic type.\r
-If V is larger than the generic type, then V is truncated to the generic type\r
-size and the low-order bits used.\r
-\r
-1. `DW_OP_lit0`, `DW_OP_lit1`, ..., `DW_OP_lit31`\r
-\r
- `DW_OP_lit<N>` operations encode an unsigned literal value N from 0 through\r
- 31, inclusive. They push the value N with the generic type.\r
-\r
-2. `DW_OP_const1u`, `DW_OP_const2u`, `DW_OP_const4u`, `DW_OP_const8u`\r
-\r
- `DW_OP_const<N>u` operations have a single operand that is a 1, 2, 4, or\r
- 8-byte unsigned integer constant U, respectively. They push the value U with\r
- the generic type.\r
-\r
-3. `DW_OP_const1s`, `DW_OP_const2s`, `DW_OP_const4s`, `DW_OP_const8s`\r
-\r
- `DW_OP_const<N>s` operations have a single operand that is a 1, 2, 4, or\r
- 8-byte signed integer constant S, respectively. They push the value S with\r
- the generic type.\r
-\r
-4. `DW_OP_constu`\r
-\r
- `DW_OP_constu` has a single unsigned LEB128 integer operand N. It pushes the\r
- value N with the generic type.\r
-\r
-5. `DW_OP_consts`\r
-\r
- `DW_OP_consts` has a single signed LEB128 integer operand N. It pushes the\r
- value N with the generic type.\r
-\r
-6. `DW_OP_constx`\r
-\r
- `DW_OP_constx` has a single unsigned LEB128 integer operand that represents\r
- a zero-based index into the `.debug_addr` section relative to the value of\r
- the `DW_AT_addr_base` attribute of the associated compilation unit. The\r
- value N in the `.debug_addr` section has the size of the generic type. It\r
- pushes the value N with the generic type.\r
-\r
- <i>The `DW_OP_constx` operation is provided for constants that require\r
- link-time relocation but should not be interpreted by the consumer as a\r
- relocatable address (for example, offsets to thread-local storage).</i>\r
-\r
-7. `DW_OP_const_type`\r
-\r
- `DW_OP_const_type` has three operands. The first is an unsigned LEB128\r
- integer DR that represents the byte offset of a debugging information entry\r
- D relative to the beginning of the current compilation unit, that provides\r
- the type T of the constant value. The second is a 1-byte unsigned integral\r
- constant S. The third is a block of bytes B, with a length equal to S.\r
-\r
- TS is the bit size of the type T. The least significant TS bits of B are\r
- interpreted as a value V of the type D. It pushes the value V with the type\r
- D.\r
-\r
- The DWARF is ill-formed if D is not a `DW_TAG_base_type` debugging\r
- information entry in the current compilation unit, or if TS divided by 8\r
- (the byte size) and rounded up to a whole number is not equal to S.\r
-\r
- <i>While the size of the byte block B can be inferred from the type D\r
- definition, it is encoded explicitly into the operation so that the\r
- operation can be parsed easily without reference to the `.debug_info`\r
- section.</i>\r
-\r
-###### A.2.5.4.3.2 Arithmetic and Logical Operations\r
-\r
-> NOTE: This section is the same as DWARF Version 5 section 2.5.1.4.\r
-\r
-###### A.2.5.4.3.3 Type Conversion Operations\r
-\r
-> NOTE: This section is the same as DWARF Version 5 section 2.5.1.6.\r
-\r
-###### A.2.5.4.3.4 Special Value Operations\r
-\r
-> NOTE: This section replaces parts of DWARF Version 5 sections 2.5.1.2,\r
- 2.5.1.3, and 2.5.1.7.\r
-\r
-There are these special value operations currently defined:\r
-\r
-1. `DW_OP_regval_type`\r
-\r
- `DW_OP_regval_type` has two operands. The first is an unsigned LEB128\r
- integer that represents a register number R. The second is an unsigned\r
- LEB128 integer DR that represents the byte offset of a debugging information\r
- entry D relative to the beginning of the current compilation unit, that\r
- provides the type T of the register value.\r
-\r
- The operation is equivalent to performing `DW_OP_regx R; DW_OP_deref_type\r
- DR`.\r
-\r
- > NOTE: Should DWARF allow the type T to be a larger size than the size of\r
- > the register R? Restricting a larger bit size avoids any issue of\r
- > conversion as the, possibly truncated, bit contents of the register is\r
- > simply interpreted as a value of T. If a conversion is wanted it can be\r
- > done explicitly using a `DW_OP_convert` operation.\r
- >\r
- > GDB has a per register hook that allows a target specific conversion on a\r
- > register by register basis. It defaults to truncation of bigger registers.\r
- > Removing use of the target hook does not cause any test failures in common\r
- > architectures. If the compiler for a target architecture did want some\r
- > form of conversion, including a larger result type, it could always\r
- > explicitly used the `DW_OP_convert` operation.\r
- >\r
- > If T is a larger type than the register size, then the default GDB\r
- > register hook reads bytes from the next register (or reads out of bounds\r
- > for the last register!). Removing use of the target hook does not cause\r
- > any test failures in common architectures (except an illegal hand written\r
- > assembly test). If a target architecture requires this behavior, these\r
- > extensions allow a composite location description to be used to combine\r
- > multiple registers.\r
-\r
-2. `DW_OP_deref`\r
-\r
- S is the bit size of the generic type divided by 8 (the byte size) and\r
- rounded up to a whole number. DR is the offset of a hypothetical debug\r
- information entry D in the current compilation unit for a base type of the\r
- generic type.\r
-\r
- The operation is equivalent to performing `DW_OP_deref_type S, DR`.\r
-\r
-3. `DW_OP_deref_size`\r
-\r
- `DW_OP_deref_size` has a single 1-byte unsigned integral constant that\r
- represents a byte result size S.\r
-\r
- TS is the smaller of the generic type bit size and S scaled by 8 (the byte\r
- size). If TS is smaller than the generic type bit size then T is an unsigned\r
- integral type of bit size TS, otherwise T is the generic type. DR is the\r
- offset of a hypothetical debug information entry D in the current\r
- compilation unit for a base type T.\r
-\r
- > NOTE: Truncating the value when S is larger than the generic type matches\r
- > what GDB does. This allows the generic type size to not be an integral\r
- > byte size. It does allow S to be arbitrarily large. Should S be restricted\r
- > to the size of the generic type rounded up to a multiple of 8?\r
-\r
- The operation is equivalent to performing `DW_OP_deref_type S, DR`, except\r
- if T is not the generic type, the value V pushed is zero-extended to the\r
- generic type bit size and its type changed to the generic type.\r
-\r
-4. `DW_OP_deref_type`\r
-\r
- `DW_OP_deref_type` has two operands. The first is a 1-byte unsigned integral\r
- constant S. The second is an unsigned LEB128 integer DR that represents the\r
- byte offset of a debugging information entry D relative to the beginning of\r
- the current compilation unit, that provides the type T of the result value.\r
-\r
- TS is the bit size of the type T.\r
-\r
- <i>While the size of the pushed value V can be inferred from the type T, it\r
- is encoded explicitly as the operand S so that the operation can be parsed\r
- easily without reference to the `.debug_info` section.</i>\r
-\r
- > NOTE: It is unclear why the operand S is needed. Unlike\r
- > `DW_OP_const_type`, the size is not needed for parsing. Any evaluation\r
- > needs to get the base type T to push with the value to know its encoding\r
- > and bit size.\r
-\r
- It pops one stack entry that must be a location description L.\r
-\r
- A value V of TS bits is retrieved from the location storage LS specified by\r
- one of the single location descriptions SL of L.\r
-\r
- <i>If L, or the location description of any composite location description\r
- part that is a subcomponent of L, has more than one single location\r
- description, then any one of them can be selected as they are required to\r
- all have the same value. For any single location description SL, bits are\r
- retrieved from the associated storage location starting at the bit offset\r
- specified by SL. For a composite location description, the retrieved bits\r
- are the concatenation of the N bits from each composite location part PL,\r
- where N is limited to the size of PL.</i>\r
-\r
- V is pushed on the stack with the type T.\r
-\r
- > NOTE: This definition makes it an evaluation error if L is a register\r
- > location description that has less than TS bits remaining in the register\r
- > storage. Particularly since these extensions extend location descriptions\r
- > to have a bit offset, it would be odd to define this as performing sign\r
- > extension based on the type, or be target architecture dependent, as the\r
- > number of remaining bits could be any number. This matches the GDB\r
- > implementation for `DW_OP_deref_type`.\r
- >\r
- > These extensions define `DW_OP_*breg*` in terms of `DW_OP_regval_type`.\r
- > `DW_OP_regval_type` is defined in terms of `DW_OP_regx`, which uses a 0\r
- > bit offset, and `DW_OP_deref_type`. Therefore, it requires the register\r
- > size to be greater or equal to the address size of the address space. This\r
- > matches the GDB implementation for `DW_OP_*breg*`.\r
-\r
- The DWARF is ill-formed if D is not in the current compilation unit, D is\r
- not a `DW_TAG_base_type` debugging information entry, or if TS divided by 8\r
- (the byte size) and rounded up to a whole number is not equal to S.\r
-\r
- > NOTE: This definition allows the base type to be a bit size since there\r
- > seems no reason to restrict it.\r
-\r
- It is an evaluation error if any bit of the value is retrieved from the\r
- undefined location storage or the offset of any bit exceeds the size of the\r
- location storage LS specified by any single location description SL of L.\r
-\r
- See [2.5.4.4.5 Implicit Location Description\r
- Operations](#implicit-location-description-operations) for special\r
- rules concerning implicit location descriptions created by the\r
- `DW_OP_implicit_pointer` operation.\r
-\r
-5. `DW_OP_xderef`\r
-\r
- `DW_OP_xderef` pops two stack entries. The first must be an integral type\r
- value that represents an address A. The second must be an integral type\r
- value that represents a target architecture specific address space\r
- identifier AS.\r
-\r
- The address size S is defined as the address bit size of the target\r
- architecture specific address space that corresponds to AS.\r
-\r
- A is adjusted to S bits by zero extending if necessary, and then treating\r
- the least significant S bits as an unsigned value A'.\r
-\r
- It creates a location description L with one memory location description SL.\r
- SL specifies the memory location storage LS that corresponds to AS with a\r
- bit offset equal to A' scaled by 8 (the byte size).\r
-\r
- If AS is an address space that is specific to context elements, then LS\r
- corresponds to the location storage associated with the current context.\r
-\r
- <i>For example, if AS is for per thread storage then LS is the location\r
- storage for the current thread. Therefore, if L is accessed by an operation,\r
- the location storage selected when the location description was created is\r
- accessed, and not the location storage associated with the current context\r
- of the access operation.</i>\r
-\r
- The DWARF expression is ill-formed if AS is not one of the values defined by\r
- the target architecture specific `DW_ASPACE_*` values.\r
-\r
- The operation is equivalent to popping A and AS, pushing L, and then\r
- performing `DW_OP_deref`. The value V retrieved is left on the stack with\r
- the generic type.\r
-\r
-6. `DW_OP_xderef_size`\r
-\r
- `DW_OP_xderef_size` has a single 1-byte unsigned integral constant that\r
- represents a byte result size S.\r
-\r
- It pops two stack entries. The first must be an integral type value\r
- that represents an address A. The second must be an integral type\r
- value that represents a target architecture specific address space\r
- identifier AS.\r
-\r
- It creates a location description L as described for `DW_OP_xderef`.\r
-\r
- The operation is equivalent to popping A and AS, pushing L, and then\r
- performing `DW_OP_deref_size S` . The zero-extended value V retrieved is\r
- left on the stack with the generic type.\r
-\r
-7. `DW_OP_xderef_type`\r
-\r
- `DW_OP_xderef_type` has two operands. The first is a 1-byte unsigned\r
- integral constant S. The second operand is an unsigned LEB128 integer DR\r
- that represents the byte offset of a debugging information entry D relative\r
- to the beginning of the current compilation unit, that provides the type T\r
- of the result value.\r
-\r
- It pops two stack entries. The first must be an integral type value that\r
- represents an address A. The second must be an integral type value that\r
- represents a target architecture specific address space identifier AS.\r
-\r
- It creates a location description L as described for `DW_OP_xderef`.\r
-\r
- The operation is equivalent to popping A and AS, pushing L, and then\r
- performing `DW_OP_deref_type DR` . The value V retrieved is left on the\r
- stack with the type T.\r
-\r
-8. `DW_OP_entry_value` <i>Deprecated</i>\r
-\r
- `DW_OP_entry_value` pushes the value of an expression that is evaluated in\r
- the context of the calling frame.\r
-\r
- <i>It may be used to determine the value of arguments on entry to the\r
- current call frame provided they are not clobbered.</i>\r
-\r
- It has two operands. The first is an unsigned LEB128 integer S. The second\r
- is a block of bytes, with a length equal S, interpreted as a DWARF operation\r
- expression E.\r
-\r
- E is evaluated with the current context, except the result kind is\r
- unspecified, the call frame is the one that called the current frame, the\r
- program location is the call site in the calling frame, the object is\r
- unspecified, and the initial stack is empty. The calling frame information\r
- is obtained by virtually unwinding the current call frame using the call\r
- frame information (see [6.4 Call Frame\r
- Information](#call-frame-information)).\r
-\r
- If the result of E is a location description L (see [2.5.4.4.4 Register\r
- Location Description\r
- Operations](#register-location-description-operations)), and the last\r
- operation executed by E is a `DW_OP_reg*` for register R with a target\r
- architecture specific base type of T, then the contents of the register are\r
- retrieved as if a `DW_OP_deref_type DR` operation was performed where DR is\r
- the offset of a hypothetical debug information entry in the current\r
- compilation unit for T. The resulting value V s pushed on the stack.\r
-\r
- <i>Using `DW_OP_reg*` provides a more compact form for the case where the\r
- value was in a register on entry to the subprogram.</i>\r
-\r
- > NOTE: It is unclear how this provides a more compact expression, as\r
- > `DW_OP_regval_type` could be used which is marginally larger.\r
-\r
- If the result of E is a value V, then V is pushed on the stack.\r
-\r
- Otherwise, the DWARF expression is ill-formed.\r
-\r
- <i>The `DW_OP_entry_value` operation is deprecated as its main usage is\r
- provided by other means. DWARF Version 5 added the\r
- `DW_TAG_call_site_parameter` debugger information entry for call sites that\r
- has `DW_AT_call_value`, `DW_AT_call_data_location`, and\r
- `DW_AT_call_data_value` attributes that provide DWARF expressions to compute\r
- actual parameter values at the time of the call, and requires the producer\r
- to ensure the expressions are valid to evaluate even when virtually\r
- unwound.</i>\r
-\r
- > NOTE: GDB only implements `DW_OP_entry_value` when E is exactly\r
- > `DW_OP_reg*` or `DW_OP_breg*; DW_OP_deref*`.\r
-\r
-##### A.2.5.4.4 Location Description Operations\r
-\r
-This section describes the operations that push location descriptions on the\r
-stack.\r
-\r
-###### A.2.5.4.4.1 General Location Description Operations\r
-\r
-> NOTE: This section replaces part of DWARF Version 5 section 2.5.1.3.\r
-\r
-1. `DW_OP_push_object_address`\r
-\r
- `DW_OP_push_object_address` pushes the location description L of the current\r
- object.\r
-\r
- <i>This object may correspond to an independent variable that is part of a\r
- user presented expression that is being evaluated. The object location\r
- description may be determined from the variable's own debugging information\r
- entry or it may be a component of an array, structure, or class whose\r
- address has been dynamically determined by an earlier step during user\r
- expression evaluation.</i>\r
-\r
- <i>This operation provides explicit functionality (especially for arrays\r
- involving descriptors) that is analogous to the implicit push of the base\r
- location description of a structure prior to evaluation of a\r
- `DW_AT_data_member_location` to access a data member of a structure.</i>\r
-\r
- > NOTE: This operation could be removed and the object location description\r
- > specified as the initial stack as for `DW_AT_data_member_location`.\r
- >\r
- > Or this operation could be used instead of needing to specify an initial\r
- > stack. The latter approach is more composable as access to the object may\r
- > be needed at any point of the expression, and passing it as the initial\r
- > stack requires the entire expression to be aware where on the stack it is.\r
- > If this were done, ``DW_AT_use_location`` would require a\r
- > ``DW_OP_push_object2_address`` operation for the second object.\r
- >\r
- > Or a more general way to pass an arbitrary number of arguments in and an\r
- > operation to get the Nth one such as ``DW_OP_arg N``. A vector of\r
- > arguments would then be passed in the expression context rather than an\r
- > initial stack. This could also resolve the issues with ``DW_OP_call*`` by\r
- > allowing a specific number of arguments passed in and returned to be\r
- > specified. The ``DW_OP_call*`` operation could then always execute on a\r
- > separate stack: the number of arguments would be specified in a new call\r
- > operation and taken from the callers stack, and similarly the number of\r
- > return results specified and copied from the called stack back to the\r
- > callee stack when the called expression was complete.\r
- >\r
- > The only attribute that specifies a current object is\r
- > `DW_AT_data_location` so the non-normative text seems to overstate how\r
- > this is being used. Or are there other attributes that need to state they\r
- > pass an object?\r
-\r
-###### A.2.5.4.4.2 Undefined Location Description Operations\r
-\r
-> NOTE: This section replaces DWARF Version 5 section 2.6.1.1.1.\r
-\r
-<i>The undefined location storage represents a piece or all of an object that is\r
-present in the source but not in the object code (perhaps due to optimization).\r
-Neither reading nor writing to the undefined location storage is meaningful.</i>\r
-\r
-An undefined location description specifies the undefined location storage.\r
-There is no concept of the size of the undefined location storage, nor of a bit\r
-offset for an undefined location description. The `DW_OP_*piece` operations can\r
-implicitly specify an undefined location description, allowing any size and\r
-offset to be specified, and results in a part with all undefined bits.\r
-\r
-###### A.2.5.4.4.3 Memory Location Description Operations\r
-\r
-> NOTE: This section replaces parts of DWARF Version 5 section 2.5.1.1, 2.5.1.2,\r
-> 2.5.1.3, and 2.6.1.1.2.\r
-\r
-Each of the target architecture specific address spaces has a corresponding\r
-memory location storage that denotes the linear addressable memory of that\r
-address space. The size of each memory location storage corresponds to the range\r
-of the addresses in the corresponding address space.\r
-\r
-<i>It is target architecture defined how address space location storage maps to\r
-target architecture physical memory. For example, they may be independent\r
-memory, or more than one location storage may alias the same physical memory\r
-possibly at different offsets and with different interleaving. The mapping may\r
-also be dictated by the source language address classes.</i>\r
-\r
-A memory location description specifies a memory location storage. The bit\r
-offset corresponds to a bit position within a byte of the memory. Bits accessed\r
-using a memory location description, access the corresponding target\r
-architecture memory starting at the bit position within the byte specified by\r
-the bit offset.\r
-\r
-A memory location description that has a bit offset that is a multiple of 8 (the\r
-byte size) is defined to be a byte address memory location description. It has a\r
-memory byte address A that is equal to the bit offset divided by 8.\r
-\r
-A memory location description that does not have a bit offset that is a multiple\r
-of 8 (the byte size) is defined to be a bit field memory location description.\r
-It has a bit position B equal to the bit offset modulo 8, and a memory byte\r
-address A equal to the bit offset minus B that is then divided by 8.\r
-\r
-The address space AS of a memory location description is defined to be the\r
-address space that corresponds to the memory location storage associated with\r
-the memory location description.\r
-\r
-A location description that is comprised of one byte address memory location\r
-description SL is defined to be a memory byte address location description. It\r
-has a byte address equal to A and an address space equal to AS of the\r
-corresponding SL.\r
-\r
-`DW_ASPACE_none` is defined as the target architecture default address space.\r
-\r
-If a stack entry is required to be a location description, but it is a value V\r
-with the generic type, then it is implicitly converted to a location description\r
-L with one memory location description SL. SL specifies the memory location\r
-storage that corresponds to the target architecture default address space with a\r
-bit offset equal to V scaled by 8 (the byte size).\r
-\r
-> NOTE: If it is wanted to allow any integral type value to be implicitly\r
-> converted to a memory location description in the target architecture default\r
-> address space:\r
->\r
-> > If a stack entry is required to be a location description, but is a value V\r
-> > with an integral type, then it is implicitly converted to a location\r
-> > description L with a one memory location description SL. If the type size of\r
-> > V is less than the generic type size, then the value V is zero extended to\r
-> > the size of the generic type. The least significant generic type size bits\r
-> > are treated as an unsigned value to be used as an address A. SL specifies\r
-> > memory location storage corresponding to the target architecture default\r
-> > address space with a bit offset equal to A scaled by 8 (the byte size).\r
->\r
-> The implicit conversion could also be defined as target architecture specific.\r
-> For example, GDB checks if V is an integral type. If it is not it gives an\r
-> error. Otherwise, GDB zero-extends V to 64 bits. If the GDB target defines a\r
-> hook function, then it is called. The target specific hook function can modify\r
-> the 64-bit value, possibly sign extending based on the original value type.\r
-> Finally, GDB treats the 64-bit value V as a memory location address.\r
-\r
-If a stack entry is required to be a location description, but it is an implicit\r
-pointer value IPV with the target architecture default address space, then it is\r
-implicitly converted to a location description with one single location\r
-description specified by IPV. See [2.5.4.4.5 Implicit Location Description\r
-Operations](#implicit-location-description-operations).\r
-\r
-If a stack entry is required to be a value, but it is a location description L\r
-with one memory location description SL in the target architecture default\r
-address space with a bit offset B that is a multiple of 8, then it is implicitly\r
-converted to a value equal to B divided by 8 (the byte size) with the generic\r
-type.\r
-\r
-1. `DW_OP_addr`\r
-\r
- `DW_OP_addr` has a single byte constant value operand, which has the size of\r
- the generic type, that represents an address A.\r
-\r
- It pushes a location description L with one memory location description SL\r
- on the stack. SL specifies the memory location storage corresponding to the\r
- target architecture default address space with a bit offset equal to A\r
- scaled by 8 (the byte size).\r
-\r
- <i>If the DWARF is part of a code object, then A may need to be relocated.\r
- For example, in the ELF code object format, A must be adjusted by the\r
- difference between the ELF segment virtual address and the virtual address\r
- at which the segment is loaded.</i>\r
-\r
-2. `DW_OP_addrx`\r
-\r
- `DW_OP_addrx` has a single unsigned LEB128 integer operand that represents a\r
- zero-based index into the `.debug_addr` section relative to the value of the\r
- `DW_AT_addr_base` attribute of the associated compilation unit. The address\r
- value A in the `.debug_addr` section has the size of the generic type.\r
-\r
- It pushes a location description L with one memory location description SL\r
- on the stack. SL specifies the memory location storage corresponding to the\r
- target architecture default address space with a bit offset equal to A\r
- scaled by 8 (the byte size).\r
-\r
- <i>If the DWARF is part of a code object, then A may need to be relocated.\r
- For example, in the ELF code object format, A must be adjusted by the\r
- difference between the ELF segment virtual address and the virtual address\r
- at which the segment is loaded.</i>\r
-\r
-3. `DW_OP_form_tls_address`\r
-\r
- `DW_OP_form_tls_address` pops one stack entry that must be an integral type\r
- value and treats it as a thread-local storage address TA.\r
-\r
- It pushes a location description L with one memory location description SL\r
- on the stack. SL is the target architecture specific memory location\r
- description that corresponds to the thread-local storage address TA.\r
-\r
- The meaning of the thread-local storage address TA is defined by the\r
- run-time environment. If the run-time environment supports multiple\r
- thread-local storage blocks for a single thread, then the block\r
- corresponding to the executable or shared library containing this DWARF\r
- expression is used.\r
-\r
- <i>Some implementations of C, C++, Fortran, and other languages support a\r
- thread-local storage class. Variables with this storage class have distinct\r
- values and addresses in distinct threads, much as automatic variables have\r
- distinct values and addresses in each subprogram invocation. Typically,\r
- there is a single block of storage containing all thread-local variables\r
- declared in the main executable, and a separate block for the variables\r
- declared in each shared library. Each thread-local variable can then be\r
- accessed in its block using an identifier. This identifier is typically a\r
- byte offset into the block and pushed onto the DWARF stack by one of the\r
- `DW_OP_const*` operations prior to the `DW_OP_form_tls_address` operation.\r
- Computing the address of the appropriate block can be complex (in some\r
- cases, the compiler emits a function call to do it), and difficult to\r
- describe using ordinary DWARF location descriptions. Instead of forcing\r
- complex thread-local storage calculations into the DWARF expressions, the\r
- `DW_OP_form_tls_address` allows the consumer to perform the computation\r
- based on the target architecture specific run-time environment.</i>\r
-\r
-4. `DW_OP_call_frame_cfa`\r
-\r
- `DW_OP_call_frame_cfa` pushes the location description L of the Canonical\r
- Frame Address (CFA) of the current subprogram, obtained from the call frame\r
- information on the stack. See [6.4 Call Frame\r
- Information](#call-frame-information).\r
-\r
- <i>Although the value of the `DW_AT_frame_base` attribute of the debugger\r
- information entry corresponding to the current subprogram can be computed\r
- using a location list expression, in some cases this would require an\r
- extensive location list because the values of the registers used in\r
- computing the CFA change during a subprogram execution. If the call frame\r
- information is present, then it already encodes such changes, and it is\r
- space efficient to reference that using the `DW_OP_call_frame_cfa`\r
- operation.</i>\r
-\r
-5. `DW_OP_fbreg`\r
-\r
- `DW_OP_fbreg` has a single signed LEB128 integer operand that represents a\r
- byte displacement B.\r
-\r
- The location description L for the <i>frame base</i> of the current\r
- subprogram is obtained from the `DW_AT_frame_base` attribute of the debugger\r
- information entry corresponding to the current subprogram as described in\r
- [3.3.5 Low-Level Information](#low-level-information).\r
-\r
- The location description L is updated by bit offset B scaled by 8 (the byte\r
- size) and pushed on the stack.\r
-\r
-6. `DW_OP_breg0`, `DW_OP_breg1`, ..., `DW_OP_breg31`\r
-\r
- The `DW_OP_breg<N>` operations encode the numbers of up to 32 registers,\r
- numbered from 0 through 31, inclusive. The register number R corresponds to\r
- the N in the operation name.\r
-\r
- They have a single signed LEB128 integer operand that represents a byte\r
- displacement B.\r
-\r
- The address space identifier AS is defined as the one corresponding to the\r
- target architecture specific default address space.\r
-\r
- The address size S is defined as the address bit size of the target\r
- architecture specific address space corresponding to AS.\r
-\r
- The contents of the register specified by R are retrieved as if a\r
- `DW_OP_regval_type R, DR` operation was performed where DR is the offset of\r
- a hypothetical debug information entry in the current compilation unit for\r
- an unsigned integral base type of size S bits. B is added and the least\r
- significant S bits are treated as an unsigned value to be used as an address\r
- A.\r
-\r
- They push a location description L comprising one memory location\r
- description LS on the stack. LS specifies the memory location storage that\r
- corresponds to AS with a bit offset equal to A scaled by 8 (the byte size).\r
-\r
-7. `DW_OP_bregx`\r
-\r
- `DW_OP_bregx` has two operands. The first is an unsigned LEB128 integer that\r
- represents a register number R. The second is a signed LEB128 integer that\r
- represents a byte displacement B.\r
-\r
- The action is the same as for `DW_OP_breg<N>`, except that R is used as the\r
- register number and B is used as the byte displacement.\r
-\r
-###### A.2.5.4.4.4 Register Location Description Operations\r
-\r
-> NOTE: This section replaces DWARF Version 5 section 2.6.1.1.3.\r
-\r
-There is a register location storage that corresponds to each of the target\r
-architecture registers. The size of each register location storage corresponds\r
-to the size of the corresponding target architecture register.\r
-\r
-A register location description specifies a register location storage. The bit\r
-offset corresponds to a bit position within the register. Bits accessed using a\r
-register location description access the corresponding target architecture\r
-register starting at the specified bit offset.\r
-\r
-1. `DW_OP_reg0`, `DW_OP_reg1`, ..., `DW_OP_reg31`\r
-\r
- `DW_OP_reg<N>` operations encode the numbers of up to 32 registers, numbered\r
- from 0 through 31, inclusive. The target architecture register number R\r
- corresponds to the N in the operation name.\r
-\r
- The operation is equivalent to performing `DW_OP_regx R`.\r
-\r
-2. `DW_OP_regx`\r
-\r
- `DW_OP_regx` has a single unsigned LEB128 integer operand that represents a\r
- target architecture register number R.\r
-\r
- If the current call frame is the top call frame, it pushes a location\r
- description L that specifies one register location description SL on the\r
- stack. SL specifies the register location storage that corresponds to R with\r
- a bit offset of 0 for the current thread.\r
-\r
- If the current call frame is not the top call frame, call frame information\r
- (see [6.4 Call Frame Information](#call-frame-information)) is used to\r
- determine the location description that holds the register for the current\r
- call frame and current program location of the current thread. The resulting\r
- location description L is pushed.\r
-\r
- <i>Note that if call frame information is used, the resulting location\r
- description may be register, memory, or undefined.</i>\r
-\r
- <i>An implementation may evaluate the call frame information immediately, or\r
- may defer evaluation until L is accessed by an operation. If evaluation is\r
- deferred, R and the current context can be recorded in L. When accessed, the\r
- recorded context is used to evaluate the call frame information, not the\r
- current context of the access operation.</i>\r
-\r
-<i>These operations obtain a register location. To fetch the contents of a\r
-register, it is necessary to use `DW_OP_regval_type`, use one of the\r
-`DW_OP_breg*` register-based addressing operations, or use `DW_OP_deref*` on a\r
-register location description.</i>\r
-\r
-###### A.2.5.4.4.5 Implicit Location Description Operations\r
-\r
-> NOTE: This section replaces DWARF Version 5 section 2.6.1.1.4.\r
-\r
-Implicit location storage represents a piece or all of an object which has no\r
-actual location in the program but whose contents are nonetheless known, either\r
-as a constant or can be computed from other locations and values in the program.\r
-\r
-An implicit location description specifies an implicit location storage. The bit\r
-offset corresponds to a bit position within the implicit location storage. Bits\r
-accessed using an implicit location description, access the corresponding\r
-implicit storage value starting at the bit offset.\r
-\r
-1. `DW_OP_implicit_value`\r
-\r
- `DW_OP_implicit_value` has two operands. The first is an unsigned LEB128\r
- integer that represents a byte size S. The second is a block of bytes with a\r
- length equal to S treated as a literal value V.\r
-\r
- An implicit location storage LS is created with the literal value V and a\r
- size of S.\r
-\r
- It pushes location description L with one implicit location description SL\r
- on the stack. SL specifies LS with a bit offset of 0.\r
-\r
-2. `DW_OP_stack_value`\r
-\r
- `DW_OP_stack_value` pops one stack entry that must be a value V.\r
-\r
- An implicit location storage LS is created with the literal value V using\r
- the size, encoding, and enianity specified by V's base type.\r
-\r
- It pushes a location description L with one implicit location description SL\r
- on the stack. SL specifies LS with a bit offset of 0.\r
-\r
- <i>The `DW_OP_stack_value` operation specifies that the object does not\r
- exist in memory, but its value is nonetheless known. In this form, the\r
- location description specifies the actual value of the object, rather than\r
- specifying the memory or register storage that holds the value.</i>\r
-\r
- See [2.5.4.4.5 Implicit Location Description\r
- Operations](#implicit-location-description-operations) for special\r
- rules concerning implicit pointer values produced by dereferencing implicit\r
- location descriptions created by the `DW_OP_implicit_pointer` operation.\r
-\r
- > NOTE: Since location descriptions are allowed on the stack, the\r
- > `DW_OP_stack_value` operation no longer terminates the DWARF operation\r
- > expression execution as in DWARF Version 5.\r
-\r
-3. `DW_OP_implicit_pointer`\r
-\r
- <i>An optimizing compiler may eliminate a pointer, while still retaining the\r
- value that the pointer addressed. `DW_OP_implicit_pointer` allows a producer\r
- to describe this value.</i>\r
-\r
- <i>`DW_OP_implicit_pointer` specifies an object is a pointer to the target\r
- architecture default address space that cannot be represented as a real\r
- pointer, even though the value it would point to can be described. In this\r
- form, the location description specifies a debugging information entry that\r
- represents the actual location description of the object to which the\r
- pointer would point. Thus, a consumer of the debug information would be able\r
- to access the dereferenced pointer, even when it cannot access the pointer\r
- itself.</i>\r
-\r
- `DW_OP_implicit_pointer` has two operands. The first operand is a 4-byte\r
- unsigned value in the 32-bit DWARF format, or an 8-byte unsigned value in\r
- the 64-bit DWARF format, that represents the byte offset DR of a debugging\r
- information entry D relative to the beginning of the `.debug_info` section\r
- that contains the current compilation unit. The second operand is a signed\r
- LEB128 integer that represents a byte displacement B.\r
-\r
- <i>Note that D may not be in the current compilation unit.</i>\r
-\r
- <i>The first operand interpretation is exactly like that for\r
- `DW_FORM_ref_addr`.</i>\r
-\r
- The address space identifier AS is defined as the one corresponding to the\r
- target architecture specific default address space.\r
-\r
- The address size S is defined as the address bit size of the target\r
- architecture specific address space corresponding to AS.\r
-\r
- An implicit location storage LS is created with the debugging information\r
- entry D, address space AS, and size of S.\r
-\r
- It pushes a location description L that comprises one implicit location\r
- description SL on the stack. SL specifies LS with a bit offset of 0.\r
-\r
- It is an evaluation error if a `DW_OP_deref*` operation pops a location\r
- description L', and retrieves S bits, such that any retrieved bits come from\r
- an implicit location storage that is the same as LS, unless both the\r
- following conditions are met:\r
-\r
- 1. All retrieved bits come from an implicit location description that\r
- refers to an implicit location storage that is the same as LS.\r
-\r
- <i>Note that all bits do not have to come from the same implicit\r
- location description, as L' may involve composite location\r
- descriptors.</i>\r
-\r
- 2. The bits come from consecutive ascending offsets within their respective\r
- implicit location storage.\r
-\r
- <i>These rules are equivalent to retrieving the complete contents of LS.</i>\r
-\r
- If both the above conditions are met, then the value V pushed by the\r
- `DW_OP_deref*` operation is an implicit pointer value IPV with a target\r
- architecture specific address space of AS, a debugging information entry of\r
- D, and a base type of T. If AS is the target architecture default address\r
- space, then T is the generic type. Otherwise, T is a target architecture\r
- specific integral type with a bit size equal to S.\r
-\r
- If IPV is either implicitly converted to a location description (only done\r
- if AS is the target architecture default address space), then the resulting\r
- location description RL is:\r
-\r
- - If D has a `DW_AT_location` attribute, the DWARF expression E from the\r
- `DW_AT_location` attribute is evaluated with the current context, except\r
- that the result kind is a location description, the compilation unit is\r
- the one that contains D, the object is unspecified, and the initial stack\r
- is empty. RL is the expression result.\r
-\r
- <i>Note that E is evaluated with the context of the expression accessing\r
- IPV, and not the context of the expression that contained the\r
- `DW_OP_implicit_pointer` operation that created L.</i>\r
-\r
- - If D has a `DW_AT_const_value` attribute, then an implicit location\r
- storage RLS is created from the `DW_AT_const_value` attribute's value with\r
- a size matching the size of the `DW_AT_const_value` attribute's value. RL\r
- comprises one implicit location description SRL. SRL specifies RLS with a\r
- bit offset of 0.\r
-\r
- > NOTE: If using `DW_AT_const_value` for variables and formal parameters\r
- > is deprecated and instead `DW_AT_location` is used with an implicit\r
- > location description, then this rule would not be required.\r
-\r
- - Otherwise, it is an evaluation error.\r
-\r
- The location description RL is updated by bit offset B scaled by 8 (the byte\r
- size).\r
-\r
- If a `DW_OP_stack_value` operation pops a value that is the same as IPV,\r
- then it pushes a location description that is the same as L.\r
-\r
- It is an evaluation error if LS or IPV is accessed in any other manner.\r
-\r
- <i>The restrictions on how an implicit pointer location description created\r
- by `DW_OP_implicit_pointer` can be used are to simplify the DWARF consumer.\r
- Similarly, for an implicit pointer value created by `DW_OP_deref*` and\r
- `DW_OP_stack_value`.</i>\r
-\r
-<i>Typically a `DW_OP_implicit_pointer` operation is used in a DWARF expression\r
-E<sub>1</sub> of a `DW_TAG_variable` or `DW_TAG_formal_parameter` debugging\r
-information entry D<sub>1</sub>'s `DW_AT_location` attribute. The debugging\r
-information entry referenced by the `DW_OP_implicit_pointer` operation is\r
-typically itself a `DW_TAG_variable` or `DW_TAG_formal_parameter` debugging\r
-information entry D<sub>2</sub> whose `DW_AT_location` attribute gives a second\r
-DWARF expression E<sub>2</sub>.</i>\r
-\r
-<i>D<sub>1</sub> and E<sub>1</sub> are describing the location of a pointer type\r
-object. D<sub>2</sub> and E<sub>2</sub> are describing the location of the\r
-object pointed to by that pointer object.</i>\r
-\r
-<i>However, D<sub>2</sub> may be any debugging information entry that contains a\r
-`DW_AT_location` or `DW_AT_const_value` attribute (for example,\r
-`DW_TAG_dwarf_procedure`). By using E<sub>2</sub>, a consumer can reconstruct\r
-the value of the object when asked to dereference the pointer described by\r
-E<sub>1</sub> which contains the `DW_OP_implicit_pointer` operation.</i>\r
-\r
-###### A.2.5.4.4.6 Composite Location Description Operations\r
-\r
-> NOTE: This section replaces DWARF Version 5 section 2.6.1.2.\r
-\r
-A composite location storage represents an object or value which may be\r
-contained in part of another location storage or contained in parts of more than\r
-one location storage.\r
-\r
-Each part has a part location description L and a part bit size S. L can have\r
-one or more single location descriptions SL. If there are more than one SL then\r
-that indicates that part is located in more than one place. The bits of each\r
-place of the part comprise S contiguous bits from the location storage LS\r
-specified by SL starting at the bit offset specified by SL. All the bits must be\r
-within the size of LS or the DWARF expression is ill-formed.\r
-\r
-A composite location storage can have zero or more parts. The parts are\r
-contiguous such that the zero-based location storage bit index will range over\r
-each part with no gaps between them. Therefore, the size of a composite location\r
-storage is the sum of the size of its parts. The DWARF expression is ill-formed\r
-if the size of the contiguous location storage is larger than the size of the\r
-memory location storage corresponding to the largest target architecture\r
-specific address space.\r
-\r
-A composite location description specifies a composite location storage. The bit\r
-offset corresponds to a bit position within the composite location storage.\r
-\r
-There are operations that create a composite location storage.\r
-\r
-There are other operations that allow a composite location storage to be\r
-incrementally created. Each part is created by a separate operation. There may\r
-be one or more operations to create the final composite location storage. A\r
-series of such operations describes the parts of the composite location storage\r
-that are in the order that the associated part operations are executed.\r
-\r
-To support incremental creation, a composite location storage can be in an\r
-incomplete state. When an incremental operation operates on an incomplete\r
-composite location storage, it adds a new part.\r
-\r
-A composite location description that specifies a composite location storage\r
-that is incomplete is termed an incomplete composite location description. A\r
-composite location description that specifies a composite location storage that\r
-is complete is termed a complete composite location description.\r
-\r
-If the top stack entry is a location description that has one incomplete\r
-composite location description SL after the execution of an operation expression\r
-has completed, SL is converted to a complete composite location description.\r
-\r
-<i>Note that this conversion does not happen after the completion of an\r
-operation expression that is evaluated on the same stack by the `DW_OP_call*`\r
-operations. Such executions are not a separate evaluation of an operation\r
-expression, but rather the continued evaluation of the same operation expression\r
-that contains the `DW_OP_call*` operation.</i>\r
-\r
-If a stack entry is required to be a location description L, but L has an\r
-incomplete composite location description, then the DWARF expression is\r
-ill-formed. The exception is for the operations involved in incrementally\r
-creating a composite location description as described below.\r
-\r
-<i>Note that a DWARF operation expression may arbitrarily compose composite\r
-location descriptions from any other location description, including those that\r
-have multiple single location descriptions, and those that have composite\r
-location descriptions.</i>\r
-\r
-<i>The incremental composite location description operations are defined to be\r
-compatible with the definitions in DWARF Version 5.</i>\r
-\r
-1. `DW_OP_piece`\r
-\r
- `DW_OP_piece` has a single unsigned LEB128 integer that represents a byte\r
- size S.\r
-\r
- The action is based on the context:\r
-\r
- - If the stack is empty, then a location description L comprised of one\r
- incomplete composite location description SL is pushed on the stack.\r
-\r
- An incomplete composite location storage LS is created with a single part\r
- P. P specifies a location description PL and has a bit size of S scaled by\r
- 8 (the byte size). PL is comprised of one undefined location description\r
- PSL.\r
-\r
- SL specifies LS with a bit offset of 0.\r
-\r
- - Otherwise, if the top stack entry is a location description L comprised of\r
- one incomplete composite location description SL, then the incomplete\r
- composite location storage LS that SL specifies is updated to append a new\r
- part P. P specifies a location description PL and has a bit size of S\r
- scaled by 8 (the byte size). PL is comprised of one undefined location\r
- description PSL. L is left on the stack.\r
- - Otherwise, if the top stack entry is a location description or can be\r
- converted to one, then it is popped and treated as a part location\r
- description PL. Then:\r
-\r
- - If the top stack entry (after popping PL) is a location description L\r
- comprised of one incomplete composite location description SL, then the\r
- incomplete composite location storage LS that SL specifies is updated to\r
- append a new part P. P specifies the location description PL and has a\r
- bit size of S scaled by 8 (the byte size). L is left on the stack.\r
- - Otherwise, a location description L comprised of one\r
- incomplete composite location description SL is pushed on\r
- the stack.\r
-\r
- An incomplete composite location storage LS is created with a single\r
- part P. P specifies the location description PL and has a bit size of S\r
- scaled by 8 (the byte size).\r
-\r
- SL specifies LS with a bit offset of 0.\r
-\r
- - Otherwise, the DWARF expression is ill-formed\r
-\r
- <i>Many compilers store a single variable in sets of registers or store a\r
- variable partially in memory and partially in registers. `DW_OP_piece`\r
- provides a way of describing where a part of a variable is located.</i>\r
-\r
- <i>The evaluation rules for the `DW_OP_piece` operation allow it to be\r
- compatible with the DWARF Version 5 definition.</i>\r
-\r
- > NOTE: Since these extensions allow location descriptions to be entries on\r
- > the stack, a simpler operation to create composite location descriptions\r
- > could be defined. For example, just one operation that specifies how many\r
- > parts, and pops pairs of stack entries for the part size and location\r
- > description. Not only would this be a simpler operation and avoid the\r
- > complexities of incomplete composite location descriptions, but it may\r
- > also have a smaller encoding in practice. However, the desire for\r
- > compatibility with DWARF Version 5 is likely a stronger consideration.\r
-\r
-2. `DW_OP_bit_piece`\r
-\r
- `DW_OP_bit_piece` has two operands. The first is an unsigned LEB128 integer\r
- that represents the part bit size S. The second is an unsigned LEB128\r
- integer that represents a bit displacement B.\r
-\r
- The action is the same as for `DW_OP_piece`, except that any part created\r
- has the bit size S, and the location description PL of any created part is\r
- updated by a bit offset B.\r
-\r
- <i>`DW_OP_bit_piece` is used instead of `DW_OP_piece` when the piece to be\r
- assembled is not byte-sized or is not at the start of the part location\r
- description.</i>\r
-\r
-#### A.2.5.5 DWARF Location List Expressions\r
-\r
-> NOTE: This section replaces DWARF Version 5 section 2.6.2.\r
-\r
-<i>To meet the needs of recent computer architectures and optimization\r
-techniques, debugging information must be able to describe the location of an\r
-object whose location changes over the object's lifetime, and may reside at\r
-multiple locations during parts of an object's lifetime. Location list\r
-expressions are used in place of operation expressions whenever the object whose\r
-location is being described has these requirements.</i>\r
-\r
-A location list expression consists of a series of location list entries. Each\r
-location list entry is one of the following kinds:\r
-\r
-1. <i>Bounded location description</i>\r
-\r
- This kind of location list entry provides an operation expression that\r
- evaluates to the location description of an object that is valid over a\r
- lifetime bounded by a starting and ending address. The starting address is\r
- the lowest address of the address range over which the location is valid.\r
- The ending address is the address of the first location past the highest\r
- address of the address range.\r
-\r
- The location list entry matches when the current program location is within\r
- the given range.\r
-\r
- There are several kinds of bounded location description entries which differ\r
- in the way that they specify the starting and ending addresses.\r
-\r
-2. <i>Default location description</i>\r
-\r
- This kind of location list entry provides an operation expression that\r
- evaluates to the location description of an object that is valid when no\r
- bounded location description entry applies.\r
-\r
- The location list entry matches when the current program location is not\r
- within the range of any bounded location description entry.\r
-\r
-3. <i>Base address</i>\r
-\r
- This kind of location list entry provides an address to be used as the base\r
- address for beginning and ending address offsets given in certain kinds of\r
- bounded location description entries. The applicable base address of a\r
- bounded location description entry is the address specified by the closest\r
- preceding base address entry in the same location list. If there is no\r
- preceding base address entry, then the applicable base address defaults to\r
- the base address of the compilation unit (see DWARF Version 5 section\r
- 3.1.1).\r
-\r
- In the case of a compilation unit where all of the machine code is contained\r
- in a single contiguous section, no base address entry is needed.\r
-\r
-4. <i>End-of-list</i>\r
-\r
- This kind of location list entry marks the end of the location list\r
- expression.\r
-\r
-The address ranges defined by the bounded location description entries of a\r
-location list expression may overlap. When they do, they describe a situation in\r
-which an object exists simultaneously in more than one place.\r
-\r
-If all of the address ranges in a given location list expression do not\r
-collectively cover the entire range over which the object in question is\r
-defined, and there is no following default location description entry, it is\r
-assumed that the object is not available for the portion of the range that is\r
-not covered.\r
-\r
-The result of the evaluation of a DWARF location list expression is:\r
-\r
-- If the current program location is not specified, then it is an evaluation\r
- error.\r
-\r
- > NOTE: If the location list only has a single default entry, should that be\r
- > considered a match if there is no program location? If there are non-default\r
- > entries then it seems it has to be an evaluation error when there is no\r
- > program location as that indicates the location depends on the program\r
- > location which is not known.\r
-\r
-- If there are no matching location list entries, then the result is a location\r
- description that comprises one undefined location description.\r
-- Otherwise, the operation expression E of each matching location list entry is\r
- evaluated with the current context, except that the result kind is a location\r
- description, the object is unspecified, and the initial stack is empty. The\r
- location list entry result is the location description returned by the\r
- evaluation of E.\r
-\r
- The result is a location description that is comprised of the union of the\r
- single location descriptions of the location description result of each\r
- matching location list entry.\r
-\r
-A location list expression can only be used as the value of a debugger\r
-information entry attribute that is encoded using class `loclist` or\r
-`loclistsptr` (see [7.5.5 Classes and Forms](#classes-and-forms)). The value of\r
-the attribute provides an index into a separate object file section called\r
-`.debug_loclists` or `.debug_loclists.dwo` (for split DWARF object files) that\r
-contains the location list entries.\r
-\r
-A `DW_OP_call*` and `DW_OP_implicit_pointer` operation can be used to specify a\r
-debugger information entry attribute that has a location list expression.\r
-Several debugger information entry attributes allow DWARF expressions that are\r
-evaluated with an initial stack that includes a location description that may\r
-originate from the evaluation of a location list expression.\r
-\r
-<i>This location list representation, the `loclist` and `loclistsptr` class, and\r
-the related `DW_AT_loclists_base` attribute are new in DWARF Version 5. Together\r
-they eliminate most, or all of the code object relocations previously needed for\r
-location list expressions.</i>\r
-\r
-> NOTE: The rest of this section is the same as DWARF Version 5 section 2.6.2.\r
-\r
-## A.3 Program Scope Entries\r
-\r
-> NOTE: This section provides changes to existing debugger information entry\r
-> attributes. These would be incorporated into the corresponding DWARF Version 5\r
-> chapter 3 sections.\r
-\r
-### A.3.3 Subroutine and Entry Point Entries\r
-\r
-#### A.3.3.5 Low-Level Information\r
-\r
-1. A `DW_TAG_subprogram`, `DW_TAG_inlined_subroutine`, or `DW_TAG_entry_point`\r
- debugger information entry may have a `DW_AT_return_addr` attribute, whose\r
- value is a DWARF expression E.\r
-\r
- The result of the attribute is obtained by evaluating E with a context that\r
- has a result kind of a location description, an unspecified object, the\r
- compilation unit that contains E, an empty initial stack, and other context\r
- elements corresponding to the source language thread of execution upon which\r
- the user is focused, if any. The result of the evaluation is the location\r
- description L of the place where the return address for the current call\r
- frame's subprogram or entry point is stored.\r
-\r
- The DWARF is ill-formed if L is not comprised of one memory location\r
- description for one of the target architecture specific address spaces.\r
-\r
- > NOTE: It is unclear why `DW_TAG_inlined_subroutine` has a\r
- > `DW_AT_return_addr` attribute but not a `DW_AT_frame_base` or\r
- > `DW_AT_static_link` attribute. Seems it would either have all of them or\r
- > none. Since inlined subprograms do not have a call frame it seems they\r
- > would have none of these attributes.\r
-\r
-2. A `DW_TAG_subprogram` or `DW_TAG_entry_point` debugger information entry may\r
- have a `DW_AT_frame_base` attribute, whose value is a DWARF expression E.\r
-\r
- The result of the attribute is obtained by evaluating E with a context that\r
- has a result kind of a location description, an unspecified object, the\r
- compilation unit that contains E, an empty initial stack, and other context\r
- elements corresponding to the source language thread of execution upon which\r
- the user is focused, if any.\r
-\r
- The DWARF is ill-formed if E contains an `DW_OP_fbreg` operation, or the\r
- resulting location description L is not comprised of one single location\r
- description SL.\r
-\r
- If SL is a register location description for register R, then L is replaced\r
- with the result of evaluating a `DW_OP_bregx R, 0` operation. This computes\r
- the frame base memory location description in the target architecture\r
- default address space.\r
-\r
- <i>This allows the more compact `DW_OP_reg*` to be used instead of\r
- `DW_OP_breg* 0`.</i>\r
-\r
- > NOTE: This rule could be removed and require the producer to create the\r
- > required location description directly using `DW_OP_call_frame_cfa` or\r
- > `DW_OP_breg*`. This would also then allow a target to implement the call\r
- > frames within a large register.\r
-\r
- Otherwise, the DWARF is ill-formed if SL is not a memory location\r
- description in any of the target architecture specific address spaces.\r
-\r
- The resulting L is the <i>frame base</i> for the subprogram or entry point.\r
-\r
- <i>Typically, E will use the `DW_OP_call_frame_cfa` operation or be a stack\r
- pointer register plus or minus some offset.</i>\r
-\r
-3. If a `DW_TAG_subprogram` or `DW_TAG_entry_point` debugger information entry\r
- is lexically nested, it may have a `DW_AT_static_link` attribute, whose\r
- value is a DWARF expression E.\r
-\r
- The result of the attribute is obtained by evaluating E with a context that\r
- has a result kind of a location description, an unspecified object, the\r
- compilation unit that contains E, an empty initial stack, and other context\r
- elements corresponding to the source language thread of execution upon which\r
- the user is focused, if any. The result of the evaluation is the location\r
- description L of the <i>canonical frame address</i> (see [6.4 Call Frame\r
- Information](#call-frame-information)) of the relevant call frame of the\r
- subprogram instance that immediately lexically encloses the current call\r
- frame's subprogram or entry point.\r
-\r
- The DWARF is ill-formed if L is is not comprised of one memory location\r
- description for one of the target architecture specific address spaces.\r
-\r
-### A.3.4 Call Site Entries and Parameters\r
-\r
-#### A.3.4.2 Call Site Parameters\r
-\r
-1. A `DW_TAG_call_site_parameter` debugger information entry may have a\r
- `DW_AT_call_value` attribute, whose value is a DWARF operation expression\r
- E<sub>1</sub>.\r
-\r
- The result of the `DW_AT_call_value` attribute is obtained by evaluating\r
- E<sub>1</sub> with a context that has a result kind of a value, an unspecified\r
- object, the compilation unit that contains E, an empty initial stack, and other\r
- context elements corresponding to the source language thread of execution upon\r
- which the user is focused, if any. The resulting value V<sub>1</sub> is the\r
- value of the parameter at the time of the call made by the call site.\r
-\r
- For parameters passed by reference, where the code passes a pointer to a\r
- location which contains the parameter, or for reference type parameters, the\r
- `DW_TAG_call_site_parameter` debugger information entry may also have a\r
- `DW_AT_call_data_location` attribute whose value is a DWARF operation expression\r
- E<sub>2</sub>, and a `DW_AT_call_data_value` attribute whose value is a DWARF\r
- operation expression E<sub>3</sub>.\r
-\r
- The value of the `DW_AT_call_data_location` attribute is obtained by evaluating\r
- E<sub>2</sub> with a context that has a result kind of a location description,\r
- an unspecified object, the compilation unit that contains E, an empty initial\r
- stack, and other context elements corresponding to the source language thread of\r
- execution upon which the user is focused, if any. The resulting location\r
- description L<sub>2</sub> is the location where the referenced parameter lives\r
- during the call made by the call site. If E<sub>2</sub> would just be a\r
- `DW_OP_push_object_address`, then the `DW_AT_call_data_location` attribute may\r
- be omitted.\r
-\r
- > NOTE: The DWARF Version 5 implies that `DW_OP_push_object_address` may be\r
- > used but does not state what object must be specified in the context.\r
- > Either `DW_OP_push_object_address` cannot be used, or the object to be\r
- > passed in the context must be defined.\r
-\r
- The value of the `DW_AT_call_data_value` attribute is obtained by evaluating\r
- E<sub>3</sub> with a context that has a result kind of a value, an unspecified\r
- object, the compilation unit that contains E, an empty initial stack, and other\r
- context elements corresponding to the source language thread of execution upon\r
- which the user is focused, if any. The resulting value V<sub>3</sub> is the\r
- value in L<sub>2</sub> at the time of the call made by the call site.\r
-\r
- The result of these attributes is undefined if the current call frame is not for\r
- the subprogram containing the `DW_TAG_call_site_parameter` debugger information\r
- entry or the current program location is not for the call site containing the\r
- `DW_TAG_call_site_parameter` debugger information entry in the current call\r
- frame.\r
-\r
- <i>The consumer may have to virtually unwind to the call site (see [6.4 Call\r
- Frame Information](#call-frame-information)) in order to evaluate these\r
- attributes. This will ensure the source language thread of execution upon which\r
- the user is focused corresponds to the call site needed to evaluate the\r
- expression.</i>\r
-\r
- If it is not possible to avoid the expressions of these attributes from\r
- accessing registers or memory locations that might be clobbered by the\r
- subprogram being called by the call site, then the associated attribute should\r
- not be provided.\r
-\r
- <i>The reason for the restriction is that the parameter may need to be accessed\r
- during the execution of the callee. The consumer may virtually unwind from the\r
- called subprogram back to the caller and then evaluate the attribute\r
- expressions. The call frame information (see [6.4 Call Frame\r
- Information](#call-frame-information)) will not be able to restore registers\r
- that have been clobbered, and clobbered memory will no longer have the value at\r
- the time of the call.</i>\r
-\r
-### A.3.5 Lexical Block Entries\r
-\r
-> NOTE: This section is the same as DWARF Version 5 section 3.5.\r
-\r
-## A.4 Data Object and Object List Entries\r
-\r
-> NOTE: This section provides changes to existing debugger information entry\r
-> attributes. These would be incorporated into the corresponding DWARF Version 5\r
-> chapter 4 sections.\r
-\r
-### A.4.1 Data Object Entries\r
-\r
-1. Any debugging information entry describing a data object (which includes\r
- variables and parameters) or common blocks may have a `DW_AT_location`\r
- attribute, whose value is a DWARF expression E.\r
-\r
- The result of the attribute is obtained by evaluating E with a context that\r
- has a result kind of a location description, an unspecified object, the\r
- compilation unit that contains E, an empty initial stack, and other context\r
- elements corresponding to the source language thread of execution upon which\r
- the user is focused, if any. The result of the evaluation is the location\r
- description of the base of the data object.\r
-\r
- See [2.5.4.2 Control Flow Operations](#control-flow-operations) for special\r
- evaluation rules used by the `DW_OP_call*` operations.\r
-\r
- > NOTE: Delete the description of how the `DW_OP_call*` operations evaluate\r
- > a `DW_AT_location` attribute as that is now described in the operations.\r
-\r
- > NOTE: See the discussion about the `DW_AT_location` attribute in the\r
- > `DW_OP_call*` operation. Having each attribute only have a single purpose\r
- > and single execution semantics seems desirable. It makes it easier for the\r
- > consumer that no longer have to track the context. It makes it easier for\r
- > the producer as it can rely on a single semantics for each attribute.\r
- >\r
- > For that reason, limiting the `DW_AT_location` attribute to only\r
- > supporting evaluating the location description of an object, and using a\r
- > different attribute and encoding class for the evaluation of DWARF\r
- > expression <i>procedures</i> on the same operation expression stack seems\r
- > desirable.\r
-\r
-2. `DW_AT_const_value`\r
-\r
- > NOTE: Could deprecate using the `DW_AT_const_value` attribute for\r
- > `DW_TAG_variable` or `DW_TAG_formal_parameter` debugger information\r
- > entries that have been optimized to a constant. Instead, `DW_AT_location`\r
- > could be used with a DWARF expression that produces an implicit location\r
- > description now that any location description can be used within a DWARF\r
- > expression. This allows the `DW_OP_call*` operations to be used to push\r
- > the location description of any variable regardless of how it is\r
- > optimized.\r
-\r
-## A.5 Type Entries\r
-\r
-> NOTE: This section provides changes to existing debugger information entry\r
-> attributes. These would be incorporated into the corresponding DWARF Version 5\r
-> chapter 5 sections.\r
-\r
-### A.5.7 Structure, Union, Class and Interface Type Entries\r
-\r
-#### A.5.7.3 Derived or Extended Structures, Classes and Interfaces\r
-\r
-1. For a `DW_AT_data_member_location` attribute there are two cases:\r
-\r
- 1. If the attribute is an integer constant B, it provides the offset in\r
- bytes from the beginning of the containing entity.\r
-\r
- The result of the attribute is obtained by updating the bit offset of\r
- the location description of the beginning of the containing entity by B\r
- scaled by 8 (the byte size). The result is the location description of\r
- the base of the member entry.\r
-\r
- <i>If the beginning of the containing entity is not byte aligned, then\r
- the beginning of the member entry has the same bit displacement within a\r
- byte.</i>\r
-\r
- 2. Otherwise, the attribute must be a DWARF expression E which is evaluated\r
- with a context that has a result kind of a location description, an\r
- unspecified object, the compilation unit that contains E, an initial\r
- stack comprising the location description of the beginning of the\r
- containing entity, and other context elements corresponding to the\r
- source language thread of execution upon which the user is focused, if\r
- any. The result of the evaluation is the location description of the\r
- base of the member entry.\r
-\r
- > NOTE: The beginning of the containing entity can now be any location\r
- > description, including those with more than one single location\r
- > description, and those with single location descriptions that are of any\r
- > kind and have any bit offset.\r
-\r
-#### A.5.7.8 Member Function Entries\r
-\r
-1. An entry for a virtual function also has a `DW_AT_vtable_elem_location`\r
- attribute whose value is a DWARF expression E.\r
-\r
- The result of the attribute is obtained by evaluating E with a context that\r
- has a result kind of a location description, an unspecified object, the\r
- compilation unit that contains E, an initial stack comprising the location\r
- description of the object of the enclosing type, and other context elements\r
- corresponding to the source language thread of execution upon which the user\r
- is focused, if any. The result of the evaluation is the location description\r
- of the slot for the function within the virtual function table for the\r
- enclosing class.\r
-\r
-### A.5.14 Pointer to Member Type Entries\r
-\r
-1. The `DW_TAG_ptr_to_member_type` debugging information entry has a\r
- `DW_AT_use_location` attribute whose value is a DWARF expression E. It is used\r
- to compute the location description of the member of the class to which the\r
- pointer to member entry points.\r
-\r
- <i>The method used to find the location description of a given member of a\r
- class, structure, or union is common to any instance of that class, structure,\r
- or union and to any instance of the pointer to member type. The method is thus\r
- associated with the pointer to member type, rather than with each object that\r
- has a pointer to member type.</i>\r
-\r
- The `DW_AT_use_location` DWARF expression is used in conjunction with the\r
- location description for a particular object of the given pointer to member type\r
- and for a particular structure or class instance.\r
-\r
- The result of the attribute is obtained by evaluating E with a context that has\r
- a result kind of a location description, an unspecified object, the compilation\r
- unit that contains E, an initial stack comprising two entries, and other context\r
- elements corresponding to the source language thread of execution upon which the\r
- user is focused, if any. The first stack entry is the value of the pointer to\r
- member object itself. The second stack entry is the location description of the\r
- base of the entire class, structure, or union instance containing the member\r
- whose location is being calculated. The result of the evaluation is the location\r
- description of the member of the class to which the pointer to member entry\r
- points.\r
-\r
-### A.5.16 Dynamic Type Entries\r
-\r
-1. The `DW_AT_data_location` attribute may be used with any type that provides one\r
- or more levels of hidden indirection and/or run-time parameters in its\r
- representation. Its value is a DWARF operation expression E which computes the\r
- location description of the data for an object. When this attribute is omitted,\r
- the location description of the data is the same as the location description of\r
- the object.\r
-\r
- The result of the attribute is obtained by evaluating E with a context that has\r
- a result kind of a location description, an object that is the location\r
- description of the data descriptor, the compilation unit that contains E, an\r
- empty initial stack, and other context elements corresponding to the source\r
- language thread of execution upon which the user is focused, if any. The result\r
- of the evaluation is the location description of the base of the member entry.\r
-\r
- <i>E will typically involve an operation expression that begins with a\r
- `DW_OP_push_object_address` operation which loads the location description\r
- of the object which can then serve as a descriptor in subsequent\r
- calculation.</i>\r
-\r
- > NOTE: Since `DW_AT_data_member_location`, `DW_AT_use_location`, and\r
- > `DW_AT_vtable_elem_location` allow both operation expressions and location\r
- > list expressions, why does `DW_AT_data_location` not allow both? In all cases\r
- > they apply to data objects so less likely that optimization would cause\r
- > different operation expressions for different program location ranges. But if\r
- > supporting for some then should be for all.\r
- >\r
- > It seems odd this attribute is not the same as `DW_AT_data_member_location` in\r
- > having an initial stack with the location description of the object since the\r
- > expression has to need it.\r
-\r
-## A.6 Other Debugging Information\r
-\r
-> NOTE: This section provides changes to existing debugger information entry\r
-> attributes. These would be incorporated into the corresponding DWARF Version 5\r
-> chapter 6 sections.\r
-\r
-### A.6.2 Line Number Information\r
-\r
-> NOTE: This section is the same as DWARF Version 5 section 6.2.\r
-\r
-### A.6.4 Call Frame Information\r
-\r
-> NOTE: This section provides changes to DWARF Version 5 section 6.4. Register\r
-> unwind DWARF expressions are generalized to allow any location description,\r
-> including those with composite and implicit location descriptions.\r
-\r
-#### A.6.4.1 Structure of Call Frame Information\r
-\r
-The register rules are:\r
-\r
-1. <i>undefined</i>\r
-\r
- A register that has this rule has no recoverable value in the previous\r
- frame. The previous value of this register is the undefined location\r
- description (see [2.5.4.4.2 Undefined Location Description\r
- Operations](#undefined-location-description-operations)).\r
-\r
- <i>By convention, the register is not preserved by a callee.</i>\r
-\r
-2. <i>same value</i>\r
-\r
- This register has not been modified from the previous caller frame.\r
-\r
- If the current frame is the top frame, then the previous value of this\r
- register is the location description L that specifies one register location\r
- description SL. SL specifies the register location storage that corresponds\r
- to the register with a bit offset of 0 for the current thread.\r
-\r
- If the current frame is not the top frame, then the previous value of this\r
- register is the location description obtained using the call frame\r
- information for the callee frame and callee program location invoked by the\r
- current caller frame for the same register.\r
-\r
- <i>By convention, the register is preserved by the callee, but the callee\r
- has not modified it.</i>\r
-\r
-3. <i>offset(N)</i>\r
-\r
- N is a signed byte offset. The previous value of this register is saved at\r
- the location description L. Where L is the location description of the\r
- current CFA (see [2.5.4 DWARF Operation\r
- Expressions](#dwarf-operation-expressions)) updated with the bit offset N\r
- scaled by 8 (the byte size).\r
-\r
-4. <i>val_offset(N)</i>\r
-\r
- N is a signed byte offset. The previous value of this register is the memory\r
- byte address of the location description L. Where L is the location\r
- description of the current CFA (see [2.5.4 DWARF Operation\r
- Expressions](#dwarf-operation-expressions)) updated with the bit offset N\r
- scaled by 8 (the byte size).\r
-\r
- The DWARF is ill-formed if the CFA location description is not a memory byte\r
- address location description, or if the register size does not match the\r
- size of an address in the target architecture default address space.\r
-\r
- <i>Since the CFA location description is required to be a memory byte\r
- address location description, the value of val_offset(N) will also be a\r
- memory byte address location description since it is offsetting the CFA\r
- location description by N bytes. Furthermore, the value of val_offset(N)\r
- will be a memory byte address in the target architecture default address\r
- space.</i>\r
-\r
- > NOTE: Should DWARF allow the address size to be a different size to the\r
- > size of the register? Requiring them to be the same bit size avoids any\r
- > issue of conversion as the bit contents of the register is simply\r
- > interpreted as a value of the address.\r
- >\r
- > GDB has a per register hook that allows a target specific conversion on a\r
- > register by register basis. It defaults to truncation of bigger registers,\r
- > and to actually reading bytes from the next register (or reads out of\r
- > bounds for the last register) for smaller registers. There are no GDB\r
- > tests that read a register out of bounds (except an illegal hand written\r
- > assembly test).\r
-\r
-5. <i>register(R)</i>\r
-\r
- This register has been stored in another register numbered R.\r
-\r
- The previous value of this register is the location description obtained\r
- using the call frame information for the current frame and current program\r
- location for register R.\r
-\r
- The DWARF is ill-formed if the size of this register does not match the size\r
- of register R or if there is a cyclic dependency in the call frame\r
- information.\r
-\r
- > NOTE: Should this also allow R to be larger than this register? If so is\r
- > the value stored in the low order bits and it is undefined what is stored\r
- > in the extra upper bits?\r
-\r
-6. <i>expression(E)</i>\r
-\r
- The previous value of this register is located at the location description\r
- produced by evaluating the DWARF operation expression E (see [2.5.4 DWARF\r
- Operation Expressions](#dwarf-operation-expressions)).\r
-\r
- E is evaluated with the current context, except the result kind is a\r
- location description, the compilation unit is unspecified, the object is\r
- unspecified, and an initial stack comprising the location description of the\r
- current CFA (see [2.5.4 DWARF Operation\r
- Expressions](#dwarf-operation-expressions)).\r
-\r
-7. <i>val_expression(E)</i>\r
-\r
- The previous value of this register is the value produced by evaluating the\r
- DWARF operation expression E (see [2.5.4 DWARF Operation\r
- Expressions](#dwarf-operation-expressions)).\r
-\r
- E is evaluated with the current context, except the result kind is a value,\r
- the compilation unit is unspecified, the object is unspecified, and an\r
- initial stack comprising the location description of the current CFA (see\r
- [2.5.4 DWARF Operation Expressions](#dwarf-operation-expressions)).\r
-\r
- The DWARF is ill-formed if the resulting value type size does not match the\r
- register size.\r
-\r
- > NOTE: This has limited usefulness as the DWARF expression E can only\r
- > produce values up to the size of the generic type. This is due to not\r
- > allowing any operations that specify a type in a CFI operation expression.\r
- > This makes it unusable for registers that are larger than the generic\r
- > type. However, <i>expression(E)</i> can be used to create an implicit\r
- > location description of any size.\r
-\r
-8. <i>architectural</i>\r
-\r
- The rule is defined externally to this specification by the augmenter.\r
-\r
-A Common Information Entry (CIE) holds information that is shared among many\r
-Frame Description Entries (FDE). There is at least one CIE in every non-empty\r
-`.debug_frame` section. A CIE contains the following fields, in order:\r
-\r
-1. `length` (initial length)\r
-\r
- A constant that gives the number of bytes of the CIE structure, not\r
- including the length field itself. The size of the length field plus the\r
- value of length must be an integral multiple of the address size specified\r
- in the `address_size` field.\r
-\r
-2. `CIE_id` (4 or 8 bytes, see [7.4 32-Bit and 64-Bit DWARF\r
- Formats](#32-bit-and-64-bit-dwarf-formats))\r
-\r
- A constant that is used to distinguish CIEs from FDEs.\r
-\r
- In the 32-bit DWARF format, the value of the CIE id in the CIE header is\r
- 0xffffffff; in the 64-bit DWARF format, the value is 0xffffffffffffffff.\r
-\r
-3. `version` (ubyte)\r
-\r
- A version number. This number is specific to the call frame information and\r
- is independent of the DWARF version number.\r
-\r
- The value of the CIE version number is 4.\r
-\r
- > NOTE: Would this be increased to 5 to reflect the changes in these\r
- > extensions?\r
-\r
-4. `augmentation` (sequence of UTF-8 characters)\r
-\r
- A null-terminated UTF-8 string that identifies the augmentation to this CIE\r
- or to the FDEs that use it. If a reader encounters an augmentation string\r
- that is unexpected, then only the following fields can be read:\r
-\r
- - CIE: length, CIE_id, version, augmentation\r
- - FDE: length, CIE_pointer, initial_location, address_range\r
-\r
- If there is no augmentation, this value is a zero byte.\r
-\r
- <i>The augmentation string allows users to indicate that there is additional\r
- vendor and target architecture specific information in the CIE or FDE which\r
- is needed to virtually unwind a stack frame. For example, this might be\r
- information about dynamically allocated data which needs to be freed on exit\r
- from the routine.</i>\r
-\r
- <i>Because the `.debug_frame` section is useful independently of any\r
- `.debug_info` section, the augmentation string always uses UTF-8\r
- encoding.</i>\r
-\r
-5. `address_size` (ubyte)\r
-\r
- The size of a target address in this CIE and any FDEs that use it, in bytes.\r
- If a compilation unit exists for this frame, its address size must match the\r
- address size here.\r
-\r
-6. `segment_selector_size` (ubyte)\r
-\r
- The size of a segment selector in this CIE and any FDEs that use it, in\r
- bytes.\r
-\r
-7. `code_alignment_factor` (unsigned LEB128)\r
-\r
- A constant that is factored out of all advance location instructions (see\r
- [6.4.2.1 Row Creation Instructions](#row-creation-instructions)). The\r
- resulting value is `(operand * code_alignment_factor)`.\r
-\r
-8. `data_alignment_factor` (signed LEB128)\r
-\r
- A constant that is factored out of certain offset instructions (see [6.4.2.2\r
- CFA Definition Instructions](#cfa-definition-instructions) and [6.4.2.3\r
- Register Rule Instructions](#register-rule-instructions)). The\r
- resulting value is `(operand * data_alignment_factor)`.\r
-\r
-9. `return_address_register` (unsigned LEB128)\r
-\r
- An unsigned LEB128 constant that indicates which column in the rule table\r
- represents the return address of the subprogram. Note that this column might\r
- not correspond to an actual machine register.\r
-\r
- The value of the return address register is used to determine the program\r
- location of the caller frame. The program location of the top frame is the\r
- target architecture program counter value of the current thread.\r
-\r
-10. `initial_instructions` (array of ubyte)\r
-\r
- A sequence of rules that are interpreted to create the initial setting of\r
- each column in the table.\r
-\r
- The default rule for all columns before interpretation of the initial\r
- instructions is the undefined rule. However, an ABI authoring body or a\r
- compilation system authoring body may specify an alternate default value for\r
- any or all columns.\r
-\r
-11. `padding` (array of ubyte)\r
-\r
- Enough `DW_CFA_nop` instructions to make the size of this entry match the\r
- length value above.\r
-\r
-An FDE contains the following fields, in order:\r
-\r
-1. `length` (initial length)\r
-\r
- A constant that gives the number of bytes of the header and instruction\r
- stream for this subprogram, not including the length field itself. The size\r
- of the length field plus the value of length must be an integral multiple of\r
- the address size.\r
-\r
-2. `CIE_pointer` (4 or 8 bytes, see [7.4 32-Bit and 64-Bit DWARF\r
- Formats](#32-bit-and-64-bit-dwarf-formats))\r
-\r
- A constant offset into the `.debug_frame` section that denotes the CIE that\r
- is associated with this FDE.\r
-\r
-3. `initial_location` (segment selector and target address)\r
-\r
- The address of the first location associated with this table entry. If the\r
- segment_selector_size field of this FDE's CIE is non-zero, the initial\r
- location is preceded by a segment selector of the given length.\r
-\r
-4. `address_range` (target address)\r
-\r
- The number of bytes of program instructions described by this entry.\r
-\r
-5. `instructions` (array of ubyte)\r
-\r
- A sequence of table defining instructions that are described in [6.4.2 Call\r
- Frame Instructions](#call-frame-instructions).\r
-\r
-6. `padding` (array of ubyte)\r
-\r
- Enough `DW_CFA_nop` instructions to make the size of this entry match the\r
- length value above.\r
-\r
-#### A.6.4.2 Call Frame Instructions\r
-\r
-Some call frame instructions have operands that are encoded as DWARF operation\r
-expressions E (see [2.5.4 DWARF Operation\r
-Expressions](#dwarf-operation-expressions)). The DWARF operations that can be\r
-used in E have the following restrictions:\r
-\r
-- `DW_OP_addrx`, `DW_OP_call2`, `DW_OP_call4`, `DW_OP_call_ref`,\r
- `DW_OP_const_type`, `DW_OP_constx`, `DW_OP_convert`, `DW_OP_deref_type`,\r
- `DW_OP_fbreg`, `DW_OP_implicit_pointer`, `DW_OP_regval_type`,\r
- `DW_OP_reinterpret`, and `DW_OP_xderef_type` operations are not allowed\r
- because the call frame information must not depend on other debug sections.\r
-- `DW_OP_push_object_address` is not allowed because there is no object context\r
- to provide a value to push.\r
-- `DW_OP_call_frame_cfa` and `DW_OP_entry_value` are not allowed because their\r
- use would be circular.\r
-\r
-<i>Call frame instructions to which these restrictions apply include\r
-`DW_CFA_def_cfa_expression`, `DW_CFA_expression`, and\r
-`DW_CFA_val_expression`.</i>\r
-\r
-##### A.6.4.2.1 Row Creation Instructions\r
-\r
-> NOTE: These instructions are the same as in DWARF Version 5 section 6.4.2.1.\r
-\r
-##### A.6.4.2.2 CFA Definition Instructions\r
-\r
-1. `DW_CFA_def_cfa`\r
-\r
- The `DW_CFA_def_cfa` instruction takes two unsigned LEB128 operands\r
- representing a register number R and a (non-factored) byte displacement B.\r
- The required action is to define the current CFA rule to be the result of\r
- evaluating the DWARF operation expression `DW_OP_bregx R, B` as a location\r
- description.\r
-\r
-2. `DW_CFA_def_cfa_sf`\r
-\r
- The `DW_CFA_def_cfa_sf` instruction takes two operands: an unsigned LEB128\r
- value representing a register number R and a signed LEB128 factored byte\r
- displacement B. The required action is to define the current CFA rule to be\r
- the result of evaluating the DWARF operation expression `DW_OP_bregx R, B *\r
- data_alignment_factor` as a location description.\r
-\r
- <i>The action is the same as `DW_CFA_def_cfa`, except that the second\r
- operand is signed and factored.</i>\r
-\r
-3. `DW_CFA_def_cfa_register`\r
-\r
- The `DW_CFA_def_cfa_register` instruction takes a single unsigned LEB128\r
- operand representing a register number R. The required action is to define\r
- the current CFA rule to be the result of evaluating the DWARF operation\r
- expression `DW_OP_bregx R, B` as a location description. B is the old CFA\r
- byte displacement.\r
-\r
- If the subprogram has no current CFA rule, or the rule was defined by a\r
- `DW_CFA_def_cfa_expression` instruction, then the DWARF is ill-formed.\r
-\r
-4. `DW_CFA_def_cfa_offset`\r
-\r
- The `DW_CFA_def_cfa_offset` instruction takes a single unsigned LEB128\r
- operand representing a (non-factored) byte displacement B. The required\r
- action is to define the current CFA rule to be the result of evaluating the\r
- DWARF operation expression `DW_OP_bregx R, B` as a location description. R\r
- is the old CFA register number.\r
-\r
- If the subprogram has no current CFA rule, or the rule was defined by a\r
- `DW_CFA_def_cfa_expression` instruction, then the DWARF is ill-formed.\r
-\r
-5. `DW_CFA_def_cfa_offset_sf`\r
-\r
- The `DW_CFA_def_cfa_offset_sf` instruction takes a signed LEB128 operand\r
- representing a factored byte displacement B. The required action is to\r
- define the current CFA rule to be the result of evaluating the DWARF\r
- operation expression `DW_OP_bregx R, B * data_alignment_factor` as a\r
- location description. R is the old CFA register number.\r
-\r
- If the subprogram has no current CFA rule, or the rule was defined by a\r
- `DW_CFA_def_cfa_expression` instruction, then the DWARF is ill-formed.\r
-\r
- <i>The action is the same as `DW_CFA_def_cfa_offset`, except that the\r
- operand is signed and factored.</i>\r
-\r
-6. `DW_CFA_def_cfa_expression`\r
-\r
- The `DW_CFA_def_cfa_expression` instruction takes a single operand encoded\r
- as a `DW_FORM_exprloc` value representing a DWARF operation expression E.\r
- The required action is to define the current CFA rule to be the result of\r
- evaluating E with the current context, except the result kind is a location\r
- description, the compilation unit is unspecified, the object is unspecified,\r
- and an empty initial stack.\r
-\r
- <i>See [6.4.2 Call Frame Instructions](#call-frame-instructions) regarding\r
- restrictions on the DWARF expression operations that can be used in E.</i>\r
-\r
- The DWARF is ill-formed if the result of evaluating E is not a memory byte\r
- address location description.\r
-\r
-##### A.6.4.2.3 Register Rule Instructions\r
-\r
-1. `DW_CFA_undefined`\r
-\r
- The `DW_CFA_undefined` instruction takes a single unsigned LEB128 operand\r
- that represents a register number R. The required action is to set the rule\r
- for the register specified by R to `undefined`.\r
-\r
-2. `DW_CFA_same_value`\r
-\r
- The `DW_CFA_same_value` instruction takes a single unsigned LEB128 operand\r
- that represents a register number R. The required action is to set the rule\r
- for the register specified by R to `same value`.\r
-\r
-3. `DW_CFA_offset`\r
-\r
- The `DW_CFA_offset` instruction takes two operands: a register number R\r
- (encoded with the opcode) and an unsigned LEB128 constant representing a\r
- factored displacement B. The required action is to change the rule for the\r
- register specified by R to be an <i>offset(B * data_alignment_factor)</i>\r
- rule.\r
-\r
- > NOTE: Seems this should be named `DW_CFA_offset_uf` since the offset is\r
- > unsigned factored.\r
-\r
-4. `DW_CFA_offset_extended`\r
-\r
- The `DW_CFA_offset_extended` instruction takes two unsigned LEB128 operands\r
- representing a register number R and a factored displacement B. This\r
- instruction is identical to `DW_CFA_offset`, except for the encoding and\r
- size of the register operand.\r
-\r
- > NOTE: Seems this should be named `DW_CFA_offset_extended_uf` since the\r
- > displacement is unsigned factored.\r
-\r
-5. `DW_CFA_offset_extended_sf`\r
-\r
- The `DW_CFA_offset_extended_sf` instruction takes two operands: an unsigned\r
- LEB128 value representing a register number R and a signed LEB128 factored\r
- displacement B. This instruction is identical to `DW_CFA_offset_extended`,\r
- except that B is signed.\r
-\r
-6. `DW_CFA_val_offset`\r
-\r
- The `DW_CFA_val_offset` instruction takes two unsigned LEB128 operands\r
- representing a register number R and a factored displacement B. The required\r
- action is to change the rule for the register indicated by R to be a\r
- <i>val_offset(B * data_alignment_factor)</i> rule.\r
-\r
- > NOTE: Seems this should be named `DW_CFA_val_offset_uf` since the\r
- displacement is unsigned factored.\r
-\r
-7. `DW_CFA_val_offset_sf`\r
-\r
- The `DW_CFA_val_offset_sf` instruction takes two operands: an unsigned\r
- LEB128 value representing a register number R and a signed LEB128 factored\r
- displacement B. This instruction is identical to `DW_CFA_val_offset`, except\r
- that B is signed.\r
-\r
-8. `DW_CFA_register`\r
-\r
- The `DW_CFA_register` instruction takes two unsigned LEB128 operands\r
- representing register numbers R1 and R2 respectively. The required action is\r
- to set the rule for the register specified by R1 to be a <i>register(R2)</i>\r
- rule.\r
-\r
-9. `DW_CFA_expression`\r
-\r
- The `DW_CFA_expression` instruction takes two operands: an unsigned LEB128\r
- value representing a register number R, and a `DW_FORM_block` value\r
- representing a DWARF operation expression E. The required action is to\r
- change the rule for the register specified by R to be an\r
- <i>expression(E)</i> rule.\r
-\r
- <i>That is, E computes the location description where the register value can\r
- be retrieved.</i>\r
-\r
- <i>See [6.4.2 Call Frame Instructions](#call-frame-instructions) regarding\r
- restrictions on the DWARF expression operations that can be used in E.</i>\r
-\r
-10. `DW_CFA_val_expression`\r
-\r
- The `DW_CFA_val_expression` instruction takes two operands: an unsigned\r
- LEB128 value representing a register number R, and a `DW_FORM_block` value\r
- representing a DWARF operation expression E. The required action is to\r
- change the rule for the register specified by R to be a\r
- <i>val_expression(E)</i> rule.\r
-\r
- <i>That is, E computes the value of register R.</i>\r
-\r
- <i>See [6.4.2 Call Frame Instructions](#call-frame-instructions) regarding\r
- restrictions on the DWARF expression operations that can be used in E.</i>\r
-\r
- If the result of evaluating E is not a value with a base type size that\r
- matches the register size, then the DWARF is ill-formed.\r
-\r
-11. `DW_CFA_restore`\r
-\r
- The `DW_CFA_restore` instruction takes a single operand (encoded with the\r
- opcode) that represents a register number R. The required action is to\r
- change the rule for the register specified by R to the rule assigned it by\r
- the `initial_instructions` in the CIE.\r
-\r
-12. `DW_CFA_restore_extended`\r
-\r
- The `DW_CFA_restore_extended` instruction takes a single unsigned LEB128\r
- operand that represents a register number R. This instruction is identical\r
- to `DW_CFA_restore`, except for the encoding and size of the register\r
- operand.\r
-\r
-##### A.6.4.2.4 Row State Instructions\r
-\r
-> NOTE: These instructions are the same as in DWARF Version 5 section 6.4.2.4.\r
-\r
-##### A.6.4.2.5 Padding Instruction\r
-\r
-> NOTE: These instructions are the same as in DWARF Version 5 section 6.4.2.5.\r
-\r
-#### A.6.4.3 Call Frame Instruction Usage\r
-\r
-> NOTE: The same as in DWARF Version 5 section 6.4.3.\r
-\r
-#### A.6.4.4 Call Frame Calling Address\r
-\r
-> NOTE: The same as in DWARF Version 5 section 6.4.4.\r
-\r
-## A.7 Data Representation\r
-\r
-> NOTE: This section provides changes to existing debugger information entry\r
-> attributes. These would be incorporated into the corresponding DWARF Version 5\r
-> chapter 7 sections.\r
-\r
-### A.7.4 32-Bit and 64-Bit DWARF Formats\r
-\r
-> NOTE: This augments DWARF Version 5 section 7.4 list item 3's table.\r
-\r
- Form Role\r
- ------------------------ --------------------------------------\r
- DW_OP_implicit_pointer offset in `.debug_info`\r
-\r
-### A.7.5 Format of Debugging Information\r
-\r
-#### A.7.5.5 Classes and Forms\r
-\r
-> NOTE: The same as in DWARF Version 5 section 7.5.5.\r
-\r
-### A.7.7 DWARF Expressions\r
-\r
-> NOTE: Rename DWARF Version 5 section 7.7 to reflect the unification of\r
-> location descriptions into DWARF expressions.\r
-\r
-#### A.7.7.1 Operation Expressions\r
-\r
-> NOTE: Rename DWARF Version 5 section 7.7.1 and delete section 7.7.2 to reflect\r
-> the unification of location descriptions into DWARF expressions.\r
-\r
-#### A.7.7.3 Location List Expressions\r
-\r
-> NOTE: Rename DWARF Version 5 section 7.7.3 to reflect that location lists are\r
-> a kind of DWARF expression.\r
-\r
-# B. Further Information\r
-\r
-The following references provide additional information on the extension.\r
-\r
-A reference to the DWARF standard is provided.\r
-\r
-A formatted version of this extension is available on the LLVM site. It includes\r
-many figures that help illustrate the textual description, especially of the\r
-example DWARF expression evaluations.\r
-\r
-Slides and a video of a presentation at the Linux Plumbers Conference 2021\r
-related to this extension are available.\r
-\r
-The LLVM compiler extension includes the operations mentioned in the motivating\r
-examples. It also covers other extensions needed for heterogeneous devices.\r
-\r
-- [DWARF Debugging Information Format](https://dwarfstd.org/)\r
- - [DWARF Debugging Information Format Version 5](https://dwarfstd.org/Dwarf5Std.php)\r
-- [Allow Location Descriptions on the DWARF Expression Stack](https://llvm.org/docs/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack.html)\r
-- DWARF extensions for optimized SIMT/SIMD (GPU) debugging - Linux Plumbers Conference 2021\r
- - [Video](https://www.youtube.com/watch?v=QiR0ra0ymEY&t=10015s)\r
- - [Slides](https://linuxplumbersconf.org/event/11/contributions/1012/attachments/798/1505/DWARF_Extensions_for_Optimized_SIMT-SIMD_GPU_Debugging-LPC2021.pdf)\r
-- [DWARF Extensions For Heterogeneous Debugging](https://llvm.org/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.html)\r
+# Allow Location Descriptions on the DWARF Expression Stack <!-- omit in toc -->
+
+- [1. Extension](#extension)
+- [2. Heterogeneous Computing Devices](#heterogeneous-computing-devices)
+- [3. DWARF 5](#dwarf-5)
+ - [3.1 How DWARF Maps Source Language To Hardware](#how-dwarf-maps-source-language-to-hardware)
+ - [3.2 Examples](#examples)
+ - [3.2.1 Dynamic Array Size](#dynamic-array-size)
+ - [3.2.2 Variable Location in Register](#variable-location-in-register)
+ - [3.2.3 Variable Location in Memory](#variable-location-in-memory)
+ - [3.2.4 Variable Spread Across Different Locations](#variable-spread-across-different-locations)
+ - [3.2.5 Offsetting a Composite Location](#offsetting-a-composite-location)
+ - [3.3 Limitations](#limitations)
+- [4. Extension Solution](#extension-solution)
+ - [4.1 Location Description](#location-description)
+ - [4.2 Stack Location Description Operations](#stack-location-description-operations)
+ - [4.3 Examples](#examples-1)
+ - [4.3.1 Source Language Variable Spilled to Part of a Vector Register](#source-language-variable-spilled-to-part-of-a-vector-register)
+ - [4.3.2 Source Language Variable Spread Across Multiple Vector Registers](#source-language-variable-spread-across-multiple-vector-registers)
+ - [4.3.3 Source Language Variable Spread Across Multiple Kinds of Locations](#source-language-variable-spread-across-multiple-kinds-of-locations)
+ - [4.3.4 Address Spaces](#address-spaces)
+ - [4.3.5 Bit Offsets](#bit-offsets)
+ - [4.4 Call Frame Information (CFI)](#call-frame-information-cfi)
+ - [4.5 Objects Not In Byte Aligned Global Memory](#objects-not-in-byte-aligned-global-memory)
+ - [4.6 Higher Order Operations](#higher-order-operations)
+ - [4.7 Objects In Multiple Places](#objects-in-multiple-places)
+- [5. Conclusion](#conclusion)
+- [A. Changes to DWARF Debugging Information Format Version 5](#a-changes-to-dwarf-debugging-information-format-version-5)
+ - [A.2 General Description](#a-2-general-description)
+ - [A.2.5 DWARF Expressions](#a-2-5-dwarf-expressions)
+ - [A.2.5.1 DWARF Expression Evaluation Context](#a-2-5-1-dwarf-expression-evaluation-context)
+ - [A.2.5.2 DWARF Expression Value](#a-2-5-2-dwarf-expression-value)
+ - [A.2.5.3 DWARF Location Description](#a-2-5-3-dwarf-location-description)
+ - [A.2.5.4 DWARF Operation Expressions](#a-2-5-4-dwarf-operation-expressions)
+ - [A.2.5.4.1 Stack Operations](#a-2-5-4-1-stack-operations)
+ - [A.2.5.4.2 Control Flow Operations](#a-2-5-4-2-control-flow-operations)
+ - [A.2.5.4.3 Value Operations](#a-2-5-4-3-value-operations)
+ - [A.2.5.4.3.1 Literal Operations](#a-2-5-4-3-1-literal-operations)
+ - [A.2.5.4.3.2 Arithmetic and Logical Operations](#a-2-5-4-3-2-arithmetic-and-logical-operations)
+ - [A.2.5.4.3.3 Type Conversion Operations](#a-2-5-4-3-3-type-conversion-operations)
+ - [A.2.5.4.3.4 Special Value Operations](#a-2-5-4-3-4-special-value-operations)
+ - [A.2.5.4.4 Location Description Operations](#a-2-5-4-4-location-description-operations)
+ - [A.2.5.4.4.1 General Location Description Operations](#a-2-5-4-4-1-general-location-description-operations)
+ - [A.2.5.4.4.2 Undefined Location Description Operations](#a-2-5-4-4-2-undefined-location-description-operations)
+ - [A.2.5.4.4.3 Memory Location Description Operations](#a-2-5-4-4-3-memory-location-description-operations)
+ - [A.2.5.4.4.4 Register Location Description Operations](#a-2-5-4-4-4-register-location-description-operations)
+ - [A.2.5.4.4.5 Implicit Location Description Operations](#a-2-5-4-4-5-implicit-location-description-operations)
+ - [A.2.5.4.4.6 Composite Location Description Operations](#a-2-5-4-4-6-composite-location-description-operations)
+ - [A.2.5.5 DWARF Location List Expressions](#a-2-5-5-dwarf-location-list-expressions)
+ - [A.3 Program Scope Entries](#a-3-program-scope-entries)
+ - [A.3.3 Subroutine and Entry Point Entries](#a-3-3-subroutine-and-entry-point-entries)
+ - [A.3.3.5 Low-Level Information](#a-3-3-5-low-level-information)
+ - [A.3.4 Call Site Entries and Parameters](#a-3-4-call-site-entries-and-parameters)
+ - [A.3.4.2 Call Site Parameters](#a-3-4-2-call-site-parameters)
+ - [A.3.5 Lexical Block Entries](#a-3-5-lexical-block-entries)
+ - [A.4 Data Object and Object List Entries](#a-4-data-object-and-object-list-entries)
+ - [A.4.1 Data Object Entries](#a-4-1-data-object-entries)
+ - [A.5 Type Entries](#a-5-type-entries)
+ - [A.5.7 Structure, Union, Class and Interface Type Entries](#a-5-7-structure-union-class-and-interface-type-entries)
+ - [A.5.7.3 Derived or Extended Structures, Classes and Interfaces](#a-5-7-3-derived-or-extended-structures-classes-and-interfaces)
+ - [A.5.7.8 Member Function Entries](#a-5-7-8-member-function-entries)
+ - [A.5.14 Pointer to Member Type Entries](#a-5-14-pointer-to-member-type-entries)
+ - [A.5.16 Dynamic Type Entries](#a-5-16-dynamic-type-entries)
+ - [A.6 Other Debugging Information](#a-6-other-debugging-information)
+ - [A.6.2 Line Number Information](#a-6-2-line-number-information)
+ - [A.6.4 Call Frame Information](#a-6-4-call-frame-information)
+ - [A.6.4.1 Structure of Call Frame Information](#a-6-4-1-structure-of-call-frame-information)
+ - [A.6.4.2 Call Frame Instructions](#a-6-4-2-call-frame-instructions)
+ - [A.6.4.2.1 Row Creation Instructions](#a-6-4-2-1-row-creation-instructions)
+ - [A.6.4.2.2 CFA Definition Instructions](#a-6-4-2-2-cfa-definition-instructions)
+ - [A.6.4.2.3 Register Rule Instructions](#a-6-4-2-3-register-rule-instructions)
+ - [A.6.4.2.4 Row State Instructions](#a-6-4-2-4-row-state-instructions)
+ - [A.6.4.2.5 Padding Instruction](#a-6-4-2-5-padding-instruction)
+ - [A.6.4.3 Call Frame Instruction Usage](#a-6-4-3-call-frame-instruction-usage)
+ - [A.6.4.4 Call Frame Calling Address](#a-6-4-4-call-frame-calling-address)
+ - [A.7 Data Representation](#a-7-data-representation)
+ - [A.7.4 32-Bit and 64-Bit DWARF Formats](#a-7-4-32-bit-and-64-bit-dwarf-formats)
+ - [A.7.5 Format of Debugging Information](#a-7-5-format-of-debugging-information)
+ - [A.7.5.5 Classes and Forms](#a-7-5-5-classes-and-forms)
+ - [A.7.7 DWARF Expressions](#a-7-7-dwarf-expressions)
+ - [A.7.7.1 Operation Expressions](#a-7-7-1-operation-expressions)
+ - [A.7.7.3 Location List Expressions](#a-7-7-3-location-list-expressions)
+- [B. Further Information](#b-further-information)
+
+# 1. Extension
+
+In DWARF 5, expressions are evaluated using a typed value stack, a separate
+location area, and an independent loclist mechanism. This extension unifies all
+three mechanisms into a single generalized DWARF expression evaluation model
+that allows both typed values and location descriptions to be manipulated on the
+evaluation stack. Both single and multiple location descriptions are supported
+on the stack. In addition, the call frame information (CFI) is extended to
+support the full generality of location descriptions. This is done in a manner
+that is backwards compatible with DWARF 5. The extension involves changes to the
+DWARF 5 sections 2.5 (pp 26-38), 2.6 (pp 38-45), and 6.4 (pp 171-182).
+
+The extension permits operations to act on location descriptions in an
+incremental, consistent, and composable manner. It allows a small number of
+operations to be defined to address the requirements of heterogeneous devices as
+well as providing benefits to non-heterogeneous devices. It acts as a foundation
+to provide support for other issues that have been raised that would benefit all
+devices.
+
+Other approaches were explored that involved adding specialized operations and
+rules. However, these resulted in the need for more operations that did not
+compose. It also resulted in operations with context sensitive semantics and
+corner cases that had to be defined. The observation was that numerous
+specialized context sensitive operations are harder for both produces and
+consumers than a smaller number of general composable operations that have
+consistent semantics regardless of context.
+
+First, section [2. Heterogeneous Computing
+Devices](#heterogeneous-computing-devices) describes heterogeneous devices and
+the features they have that are not addressed by DWARF 5. Then section [3. DWARF
+5](#dwarf-5) presents a brief simplified overview of the DWARF 5 expression
+evaluation model that highlights the difficulties for supporting the
+heterogeneous features. Next, section [4. Extension
+Solution](#extension-solution) provides an overview of the proposal, using
+simplified examples to illustrate how it can address the issues of heterogeneous
+devices and also benefit non-heterogeneous devices. Then overall conclusions are
+covered in section [5. Conclusion](#conclusion). Appendix [A. Changes to DWARF
+Debugging Information Format Version
+5](#a-changes-to-dwarf-debugging-information-format-version-5) gives changes
+relative to the DWARF Version 5 standard. Finally, appendix [B. Further
+Information](#b-further-information) has references to further information.
+
+# 2. Heterogeneous Computing Devices
+
+GPUs and other heterogeneous computing devices have features not common to CPU
+computing devices.
+
+These devices often have many more registers than a CPU. This helps reduce
+memory accesses which tend to be more expensive than on a CPU due to the much
+larger number of threads concurrently executing. In addition to traditional
+scalar registers of a CPU, these devices often have many wide vector registers.
+
+
+
+They may support masked vector instructions that are used by the compiler to map
+high level language threads onto the lanes of the vector registers. As a
+consequence, multiple language threads execute in lockstep as the vector
+instructions are executed. This is termed single instruction multiple thread
+(SIMT) execution.
+
+
+
+GPUs can have multiple memory address spaces in addition to the single global
+memory address space of a CPU. These additional address spaces are accessed
+using distinct instructions and are often local to a particular thread or group
+of threads.
+
+For example, a GPU may have a per thread block address space that is implemented
+as scratch pad memory with explicit hardware support to isolate portions to
+specific groups of threads created as a single thread block.
+
+A GPU may also use global memory in a non linear manner. For example, to support
+providing a SIMT per lane address space efficiently, there may be instructions
+that support interleaved access.
+
+Through optimization, the source variables may be located across these different
+storage kinds. SIMT execution requires locations to be able to express selection
+of runtime defined pieces of vector registers. With the more complex locations,
+there is a benefit to be able to factorize their calculation which requires all
+location kinds to be supported uniformly, otherwise duplication is necessary.
+
+# 3. DWARF 5
+
+Before presenting the proposed solution to supporting heterogeneous devices, a
+brief overview of the DWARF 5 expression evaluation model will be given to
+highlight the aspects being addressed by the extension.
+
+## 3.1 How DWARF Maps Source Language To Hardware
+
+DWARF is a standardized way to specify debug information. It describes source
+language entities such as compilation units, functions, types, variables, etc.
+It is either embedded directly in sections of the code object executables, or
+split into separate files that they reference.
+
+DWARF maps between source program language entities and their hardware
+representations. For example:
+
+- It maps a hardware instruction program counter to a source language program
+ line, and vice versa.
+- It maps a source language function to the hardware instruction program counter
+ for its entry point.
+- It maps a source language variable to its hardware location when at a
+ particular program counter.
+- It provides information to allow virtual unwinding of hardware registers for a
+ source language function call stack.
+- In addition, it provides numerous other information about the source language
+ program.
+
+In particular, there is great diversity in the way a source language entity
+could be mapped to a hardware location. The location may involve runtime values.
+For example, a source language variable location could be:
+
+- In register.
+- At a memory address.
+- At an offset from the current stack pointer.
+- Optimized away, but with a known compiler time value.
+- Optimized away, but with an unknown value, such as happens for unused
+ variables.
+- Spread across combination of the above kinds of locations.
+- At a memory address, but also transiently loaded into registers.
+
+To support this DWARF 5 defines a rich expression language comprised of loclist
+expressions and operation expressions. Loclist expressions allow the result to
+vary depending on the PC. Operation expressions are made up of a list of
+operations that are evaluated on a simple stack machine.
+
+A DWARF expression can be used as the value of different attributes of different
+debug information entries (DIE). A DWARF expression can also be used as an
+argument to call frame information information (CFI) entry operations. An
+expression is evaluated in a context dictated by where it is used. The context
+may include:
+
+- Whether the expression needs to produce a value or the location of an entity.
+- The current execution point including process, thread, PC, and stack frame.
+- Some expressions are evaluated with the stack initialized with a specific
+ value or with the location of a base object that is available using the
+ DW_OP_push_object_address operation.
+
+## 3.2 Examples
+
+The following examples illustrate how DWARF expressions involving operations are
+evaluated in DWARF 5. DWARF also has expressions involving location lists that
+are not covered in these examples.
+
+### 3.2.1 Dynamic Array Size
+
+The first example is for an operation expression associated with a DIE attribute
+that provides the number of elements in a dynamic array type. Such an attribute
+dictates that the expression must be evaluated in the context of providing a
+value result kind.
+
+
+
+In this hypothetical example, the compiler has allocated an array descriptor in
+memory and placed the descriptor's address in architecture register SGPR0. The
+first location of the array descriptor is the runtime size of the array.
+
+A possible expression to retrieve the dynamic size of the array is:
+
+ DW_OP_regval_type SGPR0 Generic
+ DW_OP_deref
+
+The expression is evaluated one operation at a time. Operations have operands
+and can pop and push entries on a stack.
+
+
+
+The expression evaluation starts with the first DW_OP_regval_type operation.
+This operation reads the current value of an architecture register specified by
+its first operand: SGPR0. The second operand specifies the size of the data to
+read. The read value is pushed on the stack. Each stack element is a value and
+its associated type.
+
+
+
+The type must be a DWARF base type. It specifies the encoding, byte ordering,
+and size of values of the type. DWARF defines that each architecture has a
+default generic type: it is an architecture specific integral encoding and byte
+ordering, that is the size of the architecture's global memory address.
+
+The DW_OP_deref operation pops a value off the stack, treats it as a global
+memory address, and reads the contents of that location using the generic type.
+It pushes the read value on the stack as the value and its associated generic
+type.
+
+
+
+The evaluation stops when it reaches the end of the expression. The result of an
+expression that is evaluated with a value result kind context is the top element
+of the stack, which provides the value and its type.
+
+### 3.2.2 Variable Location in Register
+
+This example is for an operation expression associated with a DIE attribute that
+provides the location of a source language variable. Such an attribute dictates
+that the expression must be evaluated in the context of providing a location
+result kind.
+
+DWARF defines the locations of objects in terms of location descriptions.
+
+In this example, the compiler has allocated a source language variable in
+architecture register SGPR0.
+
+
+
+A possible expression to specify the location of the variable is:
+
+ DW_OP_regx SGPR0
+
+
+
+The DW_OP_regx operation creates a location description that specifies the
+location of the architecture register specified by the operand: SGPR0. Unlike
+values, location descriptions are not pushed on the stack. Instead they are
+conceptually placed in a location area. Unlike values, location descriptions do
+not have an associated type, they only denote the location of the base of the
+object.
+
+
+
+Again, evaluation stops when it reaches the end of the expression. The result of
+an expression that is evaluated with a location result kind context is the
+location description in the location area.
+
+### 3.2.3 Variable Location in Memory
+
+The next example is for an operation expression associated with a DIE attribute
+that provides the location of a source language variable that is allocated in a
+stack frame. The compiler has placed the stack frame pointer in architecture
+register SGPR0, and allocated the variable at offset 0x10 from the stack frame
+base. The stack frames are allocated in global memory, so SGPR0 contains a
+global memory address.
+
+
+
+A possible expression to specify the location of the variable is:
+
+ DW_OP_regval_type SGPR0 Generic
+ DW_OP_plus_uconst 0x10
+
+
+
+As in the previous example, the DW_OP_regval_type operation pushes the stack
+frame pointer global memory address onto the stack. The generic type is the size
+of a global memory address.
+
+
+
+The DW_OP_plus_uconst operation pops a value from the stack, which must have a
+type with an integral encoding, adds the value of its operand, and pushes the
+result back on the stack with the same associated type. In this example, that
+computes the global memory address of the source language variable.
+
+
+
+Evaluation stops when it reaches the end of the expression. If the expression
+that is evaluated has a location result kind context, and the location area is
+empty, then the top stack element must be a value with the generic type. The
+value is implicitly popped from the stack, and treated as a global memory
+address to create a global memory location description, which is placed in the
+location area. The result of the expression is the location description in the
+location area.
+
+
+
+### 3.2.4 Variable Spread Across Different Locations
+
+This example is for a source variable that is partly in a register, partly undefined, and partly in memory.
+
+
+
+DWARF defines composite location descriptions that can have one or more parts.
+Each part specifies a location description and the number of bytes used from it.
+The following operation expression creates a composite location description.
+
+ DW_OP_regx SGPR3
+ DW_OP_piece 4
+ DW_OP_piece 2
+ DW_OP_bregx SGPR0 0x10
+ DW_OP_piece 2
+
+
+
+The DW_OP_regx operation creates a register location description in the location
+area.
+
+
+
+The first DW_OP_piece operation creates an incomplete composite location
+description in the location area with a single part. The location description in
+the location area is used to define the beginning of the part for the size
+specified by the operand, namely 4 bytes.
+
+
+
+A subsequent DW_OP_piece adds a new part to an incomplete composite location
+description already in the location area. The parts form a contiguous set of
+bytes. If there are no other location descriptions in the location area, and no
+value on the stack, then the part implicitly uses the undefined location
+description. Again, the operand specifies the size of the part in bytes. The
+undefined location description can be used to indicate a part that has been
+optimized away. In this case, 2 bytes of undefined value.
+
+
+
+The DW_OP_bregx operation reads the architecture register specified by the first
+operand (SGPR0) as the generic type, adds the value of the second operand
+(0x10), and pushes the value on the stack.
+
+
+
+The next DW_OP_piece operation adds another part to the already created
+incomplete composite location.
+
+If there is no other location in the location area, but there is a value on
+stack, the new part is a memory location description. The memory address used is
+popped from the stack. In this case, the operand of 2 indicates there are 2
+bytes from memory.
+
+
+
+Evaluation stops when it reaches the end of the expression. If the expression
+that is evaluated has a location result kind context, and the location area has
+an incomplete composite location description, the incomplete composite location
+is implicitly converted to a complete composite location description. The result
+of the expression is the location description in the location area.
+
+
+
+### 3.2.5 Offsetting a Composite Location
+
+This example attempts to extend the previous example to offset the composite
+location description it created. The [3.2.3 Variable Location in
+Memory](#variable-location-in-memory) example conveniently used the DW_OP_plus
+operation to offset a memory address.
+
+ DW_OP_regx SGPR3
+ DW_OP_piece 4
+ DW_OP_piece 2
+ DW_OP_bregx SGPR0 0x10
+ DW_OP_piece 2
+ DW_OP_plus_uconst 5
+
+
+
+However, DW_OP_plus cannot be used to offset a composite location. It only
+operates on the stack.
+
+
+
+To offset a composite location description, the compiler would need to make a
+different composite location description, starting at the part corresponding to
+the offset. For example:
+
+ DW_OP_piece 1
+ DW_OP_bregx SGPR0 0x10
+ DW_OP_piece 2
+
+This illustrates that operations on stack values are not composable with
+operations on location descriptions.
+
+## 3.3 Limitations
+
+DWARF 5 is unable to describe variables in runtime indexed parts of registers.
+This is required to describe a source variable that is located in a lane of a
+SIMT vector register.
+
+Some features only work when located in global memory. The type attribute
+expressions require a base object which could be in any kind of location.
+
+DWARF procedures can only accept global memory address arguments. This limits
+the ability to factorize the creation of locations that involve other location
+kinds.
+
+There are no vector base types. This is required to describe vector registers.
+
+There is no operation to create a memory location in a non-global address space.
+Only the dereference operation supports providing an address space.
+
+CFI location expressions do not allow composite locations or non-global address
+space memory locations. Both these are needed in optimized code for devices with
+vector registers and address spaces.
+
+Bit field offsets are only supported in a limited way for register locations.
+Supporting them in a uniform manner for all location kinds is required to
+support languages with bit sized entities.
+
+# 4. Extension Solution
+
+This section outlines the extension to generalize the DWARF expression evaluation
+model to allow location descriptions to be manipulated on the stack. It presents
+a number of simplified examples to demonstrate the benefits and how the extension
+solves the issues of heterogeneous devices. It presents how this is done in
+a manner that is backwards compatible with DWARF 5.
+
+## 4.1 Location Description
+
+In order to have consistent, composable operations that act on location
+descriptions, the extension defines a uniform way to handle all location kinds.
+That includes memory, register, implicit, implicit pointer, undefined, and
+composite location descriptions.
+
+Each kind of location description is conceptually a zero-based offset within a
+piece of storage. The storage is a contiguous linear organization of a certain
+number of bytes (see below for how this is extended to support bit sized
+storage).
+
+- For global memory, the storage is the linear stream of bytes of the
+ architecture's address size.
+- For each separate architecture register, it is the linear stream of bytes of
+ the size of that specific register.
+- For an implicit, it is the linear stream of bytes of the value when
+ represented using the value's base type which specifies the encoding, size,
+ and byte ordering.
+- For undefined, it is an infinitely sized linear stream where every byte is
+ undefined.
+- For composite, it is a linear stream of bytes defined by the composite's parts.
+
+## 4.2 Stack Location Description Operations
+
+The DWARF expression stack is extended to allow each stack entry to either be a
+value or a location description.
+
+Evaluation rules are defined to implicitly convert a stack element that is a
+value to a location description, or vice versa, so that all DWARF 5 expressions
+continue to have the same semantics. This reflects that a memory address is
+effectively used as a proxy for a memory location description.
+
+For each place that allows a DWARF expression to be specified, it is defined if
+the expression is to be evaluated as a value or a location description.
+
+Existing DWARF expression operations that are used to act on memory addresses
+are generalized to act on any location description kind. For example, the
+DW_OP_deref operation pops a location description rather than a memory address
+value from the stack and reads the storage associated with the location kind
+starting at the location description's offset.
+
+Existing DWARF expression operations that create location descriptions are
+changed to pop and push location descriptions on the stack. For example, the
+DW_OP_value, DW_OP_regx, DW_OP_implicit_value, DW_OP_implicit_pointer,
+DW_OP_stack_value, and DW_OP_piece.
+
+New operations that act on location descriptions can be added. For example, a
+DW_OP_offset operation that modifies the offset of the location description on
+top of the stack. Unlike the DW_OP_plus operation that only works with memory
+address, a DW_OP_offset operation can work with any location kind.
+
+To allow incremental and nested creation of composite location descriptions, a
+DW_OP_piece_end can be defined to explicitly indicate the last part of a
+composite. Currently, creating a composite must always be the last operation of
+an expression.
+
+A DW_OP_undefined operation can be defined that explicitly creates the undefined
+location description. Currently this is only possible as a piece of a composite
+when the stack is empty.
+
+## 4.3 Examples
+
+This section provides some motivating examples to illustrate the benefits that
+result from allowing location descriptions on the stack.
+
+### 4.3.1 Source Language Variable Spilled to Part of a Vector Register
+
+A compiler generating code for a GPU may allocate a source language variable
+that it proves has the same value for every lane of a SIMT thread in a scalar
+register. It may then need to spill that scalar register. To avoid the high cost
+of spilling to memory, it may spill to a fixed lane of one of the numerous
+vector registers.
+
+
+
+The following expression defines the location of a source language variable that
+the compiler allocated in a scalar register, but had to spill to lane 5 of a
+vector register at this point of the code.
+
+ DW_OP_regx VGPR0
+ DW_OP_offset_uconst 20
+
+
+
+The DW_OP_regx pushes a register location description on the stack. The storage
+for the register is the size of the vector register. The register location
+description conceptually references that storage with an initial offset of 0.
+The architecture defines the byte ordering of the register.
+
+
+
+The DW_OP_offset_uconst pops a location description off the stack, adds its
+operand value to the offset, and pushes the updated location description back on
+the stack. In this case the source language variable is being spilled to lane 5
+and each lane's component which is 32-bits (4 bytes), so the offset is 5*4=20.
+
+
+
+The result of the expression evaluation is the location description on the top
+of the stack.
+
+An alternative approach could be for the target to define distinct register
+names for each part of each vector register. However, this is not practical for
+GPUs due to the sheer number of registers that would have to be defined. It
+would also not permit a runtime index into part of the whole register to be used
+as shown in the next example.
+
+### 4.3.2 Source Language Variable Spread Across Multiple Vector Registers
+
+A compiler may generate SIMT code for a GPU. Each source language thread of
+execution is mapped to a single lane of the GPU thread. Source language
+variables that are mapped to a register, are mapped to the lane component of the
+vector registers corresponding to the source language's thread of execution.
+
+The location expression for such variables must therefore be executed in the
+context of the focused source language thread of execution. A DW_OP_push_lane
+operation can be defined to push the value of the lane for the currently focused
+source language thread of execution. The value to use would be provided by the
+consumer of DWARF when it evaluates the location expression.
+
+If the source language variable is larger than the size of the vector register
+lane component, then multiple vector registers are used. Each source language
+thread of execution will only use the vector register components for its
+associated lane.
+
+
+
+The following expression defines the location of a source language variable that
+has to occupy two vector registers. A composite location description is created
+that combines the two parts. It will give the correct result regardless of which
+lane corresponds to the source language thread of execution that the user is
+focused on.
+
+ DW_OP_regx VGPR0
+ DW_OP_push_lane
+ DW_OP_uconst 4
+ DW_OP_mul
+ DW_OP_offset
+ DW_OP_piece 4
+ DW_OP_regx VGPR1
+ DW_OP_push_lane
+ DW_OP_uconst 4
+ DW_OP_mul
+ DW_OP_offset
+ DW_OP_piece 4
+
+
+
+The DW_OP_regx VGPR0 pushes a location description for the first register.
+
+
+
+The DW_OP_push_lane; DW_OP_uconst 4; DW_OP_mul calculates the offset for the
+focused lanes vector register component as 4 times the lane number.
+
+
+
+
+
+
+
+The DW_OP_offset adjusts the register location description's offset to the
+runtime computed value.
+
+
+
+The DW_OP_piece either creates a new composite location description, or adds a
+new part to an existing incomplete one. It pops the location description to use
+for the new part. It then pops the next stack element if it is an incomplete
+composite location description, otherwise it creates a new incomplete composite
+location description with no parts. Finally it pushes the incomplete composite
+after adding the new part.
+
+In this case a register location description is added to a new incomplete
+composite location description. The 4 of the DW_OP_piece specifies the size of
+the register storage that comprises the part. Note that the 4 bytes start at the
+computed register offset.
+
+For backwards compatibility, if the stack is empty or the top stack element is
+an incomplete composite, an undefined location description is used for the part.
+If the top stack element is a generic base type value, then it is implicitly
+converted to a global memory location description with an offset equal to the
+value.
+
+
+
+The rest of the expression does the same for VGPR1. However, when the
+DW_OP_piece is evaluated there is an incomplete composite on the stack. So the
+VGPR1 register location description is added as a second part.
+
+
+
+
+
+
+
+
+
+
+
+
+
+At the end of the expression, if the top stack element is an incomplete
+composite location description, it is converted to a complete location
+description and returned as the result.
+
+
+
+### 4.3.3 Source Language Variable Spread Across Multiple Kinds of Locations
+
+This example is the same as the previous one, except the first 2 bytes of the
+second vector register have been spilled to memory, and the last 2 bytes have
+been proven to be a constant and optimized away.
+
+
+
+ DW_OP_regx VGPR0
+ DW_OP_push_lane
+ DW_OP_uconst 4
+ DW_OP_mul
+ DW_OP_offset
+ DW_OP_piece 4
+ DW_OP_addr 0xbeef
+ DW_OP_piece 2
+ DW_OP_uconst 0xf00d
+ DW_OP_stack_value
+ DW_OP_piece 2
+ DW_OP_piece_end
+
+The first 6 operations are the same.
+
+
+
+The DW_OP_addr operation pushes a global memory location description on the
+stack with an offset equal to the address.
+
+
+
+The next DW_OP_piece adds the global memory location description as the next 2
+byte part of the composite.
+
+
+
+The DW_OP_uconst 0xf00d; DW_OP_stack_value pushes an implicit location
+description on the stack. The storage of the implicit location description is
+the representation of the value 0xf00d using the generic base type's encoding,
+size, and byte ordering.
+
+
+
+
+
+The final DW_OP_piece adds 2 bytes of the implicit location description as the
+third part of the composite location description.
+
+
+
+The DW_OP_piece_end operation explicitly makes the incomplete composite location
+description into a complete location description. This allows a complete
+composite location description to be created on the stack that can be used as
+the location description of another following operation. For example, the
+DW_OP_offset can be applied to it. More practically, it permits creation of
+multiple composite location descriptions on the stack which can be used to pass
+arguments to a DWARF procedure using a DW_OP_call* operation. This can be
+beneficial to factor the incrementally creation of location descriptions.
+
+
+
+### 4.3.4 Address Spaces
+
+Heterogeneous devices can have multiple hardware supported address spaces which
+use specific hardware instructions to access them.
+
+For example, GPUs that use SIMT execution may provide hardware support to access
+memory such that each lane can see a linear memory view, while the backing
+memory is actually being accessed in an interleaved manner so that the locations
+for each lanes Nth dword are contiguous. This minimizes cache lines read by the
+SIMT execution.
+
+
+
+The following expression defines the location of a source language variable that
+is allocated at offset 0x10 in the current subprograms stack frame. The
+subprogram stack frames are per lane and reside in an interleaved address space.
+
+ DW_OP_regval_type SGPR0 Generic
+ DW_OP_uconst 1
+ DW_OP_form_aspace_address
+ DW_OP_offset 0x10
+
+
+
+The DW_OP_regval_type operation pushes the contents of SGPR0 as a generic value.
+This is the register that holds the address of the current stack frame.
+
+
+
+The DW_OP_uconst operation pushes the address space number. Each architecture
+defines the numbers it uses in DWARF. In this case, address space 1 is being
+used as the per lane memory.
+
+
+
+The DW_OP_form_aspace_address operation pops a value and an address space
+number. Each address space is associated with a separate storage. A memory
+location description is pushed which refers to the address space's storage, with
+an offset of the popped value.
+
+
+
+All operations that act on location descriptions work with memory locations
+regardless of their address space.
+
+Every architecture defines address space 0 as the default global memory address
+space.
+
+Generalizing memory location descriptions to include an address space component
+avoids having to create specialized operations to work with address spaces.
+
+The source variable is at offset 0x10 in the stack frame. The DW_OP_offset
+operation works on memory location descriptions that have an address space just
+like for any other kind of location description.
+
+
+
+The only operations in DWARF 5 that take an address space are DW_OP_xderef*.
+They treat a value as the address in a specified address space, and read its
+contents. There is no operation to actually create a location description that
+references an address space. There is no way to include address space memory
+locations in parts of composite locations.
+
+Since DW_OP_piece now takes any kind of location description for its pieces, it
+is now possible for parts of a composite to involve locations in different
+address spaces. For example, this can happen when parts of a source variable
+allocated in a register are spilled to a stack frame that resides in the
+non-global address space.
+
+### 4.3.5 Bit Offsets
+
+With the generalization of location descriptions on the stack, it is possible to
+define a DW_OP_bit_offset operation that adjusts the offset of any kind of
+location in terms of bits rather than bytes. The offset can be a runtime
+computed value. This is generally useful for any source language that support
+bit sized entities, and for registers that are not a whole number of bytes.
+
+DWARF 5 only supports bit fields in composites using DW_OP_bit_piece. It does
+not support runtime computed offsets which can happen for bit field packed
+arrays. It is also not generally composable as it must be the last part of an
+expression.
+
+The following example defines a location description for a source variable that
+is allocated starting at bit 20 of a register. A similar expression could be
+used if the source variable was at a bit offset within memory or a particular
+address space, or if the offset is a runtime value.
+
+
+
+ DW_OP_regx SGPR3
+ DW_OP_uconst 20
+ DW_OP_bit_offset
+
+
+
+
+
+
+
+The DW_OP_bit_offset operation pops a value and location description from the
+stack. It pushes the location description after updating its offset using the
+value as a bit count.
+
+
+
+The ordering of bits within a byte, like byte ordering, is defined by the target
+architecture. A base type could be extended to specify bit ordering in addition
+to byte ordering.
+
+## 4.4 Call Frame Information (CFI)
+
+DWARF defines call frame information (CFI) that can be used to virtually unwind
+the subprogram call stack. This involves determining the location where register
+values have been spilled. DWARF 5 limits these locations to either be registers
+or global memory. As shown in the earlier examples, heterogeneous devices may
+spill registers to parts of other registers, to non-global memory address
+spaces, or even a composite of different location kinds.
+
+Therefore, the extension extends the CFI rules to support any kind of location
+description, and operations to create locations in address spaces.
+
+## 4.5 Objects Not In Byte Aligned Global Memory
+
+DWARF 5 only effectively supports byte aligned memory locations on the stack by
+using a global memory address as a proxy for a memory location description. This
+is a problem for attributes that define DWARF expressions that require the
+location of some source language entity that is not allocated in byte aligned
+global memory.
+
+For example, the DWARF expression of the DW_AT_data_member_location attribute is
+evaluated with an initial stack containing the location of a type instance
+object. That object could be located in a register, in a non-global memory
+address space, be described by a composite location description, or could even
+be an implicit location description.
+
+A similar problem exists for DWARF expressions that use the
+DW_OP_push_object_address operation. This operation pushes the location of a
+program object associated with the attribute that defines the expression.
+
+Allowing any kind of location description on the stack permits the DW_OP_call*
+operations to be used to factor the creation of location descriptions. The
+inputs and outputs of the call are passed on the stack. For example, on GPUs an
+expression can be defined to describe the effective PC of inactive lanes of SIMT
+execution. This is naturally done by composing the result of expressions for
+each nested control flow region. This can be done by making each control flow
+region have its own DWARF procedure, and then calling it from the expressions of
+the nested control flow regions. The alternative is to make each control flow
+region have the complete expression which results in much larger DWARF and is
+less convenient to generate.
+
+GPU compilers work hard to allocate objects in the larger number of registers to
+reduce memory accesses, they have to use different memory address spaces, and
+they perform optimizations that result in composites of these. Allowing
+operations to work with any kind of location description enables creating
+expressions that support all of these.
+
+Full general support for bit fields and implicit locations benefits
+optimizations on any target.
+
+## 4.6 Higher Order Operations
+
+The generalization allows an elegant way to add higher order operations that
+create location descriptions out of other location descriptions in a general
+composable manner.
+
+For example, a DW_OP_extend operation could create a composite location
+description out of a location description, an element size, and an element
+count. The resulting composite would effectively be a vector of element count
+elements with each element being the same location description of the specified
+bit size.
+
+A DW_OP_select_bit_piece operation could create a composite location description
+out of two location descriptions, a bit mask value, and an element size. The
+resulting composite would effectively be a vector of elements, selecting from
+one of the two input locations according to the bit mask.
+
+These could be used in the expression of an attribute that computes the
+effective PC of lanes of SIMT execution. The vector result efficiently computes
+the PC for each SIMT lane at once. The mask could be the hardware execution mask
+register that controls which SIMT lanes are executing. For active divergent
+lanes the vector element would be the current PC, and for inactive divergent
+lanes the PC would correspond to the source language line at which the lane is
+logically positioned.
+
+Similarly, a DW_OP_overlay_piece operation could be defined that creates a
+composite location description out of two location descriptions, an offset
+value, and a size. The resulting composite would consist of parts that are
+equivalent to one of the location descriptions, but with the other location
+description replacing a slice defined by the offset and size. This could be used
+to efficiently express a source language array that has had a set of elements
+promoted into a vector register when executing a set of iterations of a loop in
+a SIMD manner.
+
+## 4.7 Objects In Multiple Places
+
+A compiler may allocate a source variable in stack frame memory, but for some
+range of code may promote it to a register. If the generated code does not
+change the register value, then there is no need to save it back to memory.
+Effectively, during that range, the source variable is in both memory and a
+register. If a consumer, such as a debugger, allows the user to change the value
+of the source variable in that PC range, then it would need to change both
+places.
+
+DWARF 5 supports loclists which are able to specify the location of a source
+language entity is in different places at different PC locations. It can also
+express that a source language entity is in multiple places at the same time.
+
+DWARF 5 defines operation expressions and loclists separately. In general, this
+is adequate as non-memory location descriptions can only be computed as the last
+step of an expression evaluation.
+
+However, allowing location descriptions on the stack permits non-memory location
+descriptions to be used in the middle of expression evaluation. For example, the
+DW_OP_call* and DW_OP_implicit_pointer operations can result in evaluating the
+expression of a DW_AT_location attribute of a DIE. The DW_AT_location attribute
+allows the loclist form. So the result could include multiple location
+descriptions.
+
+Similarly, the DWARF expression associated with attributes such as
+DW_AT_data_member_location that are evaluated with an initial stack containing a
+location description, or a DWARF operation expression that uses the
+DW_OP_push_object_address operation, may want to act on the result of another
+expression that returned a location description involving multiple places.
+
+Therefore, the extension needs to define how expression operations that use those
+results will behave. The extension does this by generalizing the expression stack
+to allow an entry to be one or more single location descriptions. In doing this,
+it unifies the definitions of DWARF operation expressions and loclist
+expressions in a natural way.
+
+All operations that act on location descriptions are extended to act on multiple
+single location descriptions. For example, the DW_OP_offset operation adds the
+offset to each single location description. The DW_OP_deref* operations simply
+read the storage of one of the single location descriptions, since multiple
+single location descriptions must all hold the same value. Similarly, if the
+evaluation of a DWARF expression results in multiple single location
+descriptions, the consumer can ensure any updates are done to all of them, and
+any reads can use any one of them.
+
+# 5. Conclusion
+
+A strength of DWARF is that it has generally sought to provide generalized
+composable solutions that address many problems, rather than solutions that only
+address one-off issues. This extension attempts to follow that tradition by
+defining a backwards compatible composable generalization that can address a
+significant family of issues. It addresses the specific issues present for
+heterogeneous computing devices, provides benefits for non-heterogeneous
+devices, and can help address a number of other previously reported issues.
+
+# A. Changes to DWARF Debugging Information Format Version 5
+
+> NOTE: This appendix provides changes relative to DWARF Version 5. It has been
+> defined such that it is backwards compatible with DWARF Version 5.
+> Non-normative text is shown in <i>italics</i>. The section numbers generally
+> correspond to those in the DWARF Version 5 standard unless specified
+> otherwise. Definitions are given to clarify how existing expression
+> operations, CFI operations, and attributes behave with respect to generalized
+> location descriptions that support multiple places.
+>
+> > NOTE: Notes are included to describe how the changes are to be applied to
+> > the DWARF Version 5 standard. They also describe rational and issues that
+> > may need further consideration.
+
+## A.2 General Description
+
+### A.2.5 DWARF Expressions
+
+> NOTE: This section, and its nested sections, replaces DWARF Version 5 section
+> 2.5 and section 2.6. It is based on the text of the existing DWARF Version 5
+> standard.
+
+DWARF expressions describe how to compute a value or specify a location.
+
+<i>The evaluation of a DWARF expression can provide the location of an object,
+the value of an array bound, the length of a dynamic string, the desired value
+itself, and so on.</i>
+
+If the evaluation of a DWARF expression does not encounter an error, then it can
+either result in a value (see [2.5.2 DWARF Expression
+Value](#dwarf-expression-value)) or a location description (see [2.5.3 DWARF
+Location Description](#dwarf-location-description)). When a DWARF expression
+is evaluated, it may be specified whether a value or location description is
+required as the result kind.
+
+If a result kind is specified, and the result of the evaluation does not match
+the specified result kind, then the implicit conversions described in [2.5.4.4.3
+Memory Location Description
+Operations](#memory-location-description-operations) are performed if
+valid. Otherwise, the DWARF expression is ill-formed.
+
+If the evaluation of a DWARF expression encounters an evaluation error, then the
+result is an evaluation error.
+
+> NOTE: Decided to define the concept of an evaluation error. An alternative is
+> to introduce an undefined value base type in a similar way to location
+> descriptions having an undefined location description. Then operations that
+> encounter an evaluation error can return the undefined location description or
+> value with an undefined base type.
+>
+> All operations that act on values would return an undefined entity if given an
+> undefined value. The expression would then always evaluate to completion, and
+> can be tested to determine if it is an undefined entity.
+>
+> However, this would add considerable additional complexity and does not match
+> that GDB throws an exception when these evaluation errors occur.
+
+If a DWARF expression is ill-formed, then the result is undefined.
+
+The following sections detail the rules for when a DWARF expression is
+ill-formed or results in an evaluation error.
+
+A DWARF expression can either be encoded as an operation expression (see [2.5.4
+DWARF Operation Expressions](#dwarf-operation-expressions)), or as a
+location list expression (see [2.5.5 DWARF Location List
+Expressions](#dwarf-location-list-expressions)).
+
+#### A.2.5.1 DWARF Expression Evaluation Context
+
+A DWARF expression is evaluated in a context that can include a number of
+context elements. If multiple context elements are specified then they must be
+self consistent or the result of the evaluation is undefined. The context
+elements that can be specified are:
+
+1. <i>A current result kind</i>
+
+ The kind of result required by the DWARF expression evaluation. If specified
+ it can be a location description or a value.
+
+2. <i>A current thread</i>
+
+ The target architecture thread identifier of the source program thread of
+ execution for which a user presented expression is currently being
+ evaluated.
+
+ It is required for operations that are related to target architecture
+ threads.
+
+ <i>For example, the `DW_OP_regval_type` operation.</i>
+
+3. <i>A current call frame</i>
+
+ The target architecture call frame identifier. It identifies a call frame
+ that corresponds to an active invocation of a subprogram in the current
+ thread. It is identified by its address on the call stack. The address is
+ referred to as the Canonical Frame Address (CFA). The call frame information
+ is used to determine the CFA for the call frames of the current thread's
+ call stack (see [6.4 Call Frame Information](#call-frame-information)).
+
+ It is required for operations that specify target architecture registers to
+ support virtual unwinding of the call stack.
+
+ <i>For example, the `DW_OP_*reg*` operations.</i>
+
+ If specified, it must be an active call frame in the current thread.
+ Otherwise the result is undefined.
+
+ If it is the currently executing call frame, then it is termed the top call
+ frame.
+
+4. <i>A current program location</i>
+
+ The target architecture program location corresponding to the current call
+ frame of the current thread.
+
+ The program location of the top call frame is the target architecture
+ program counter for the current thread. The call frame information is used
+ to obtain the value of the return address register to determine the program
+ location of the other call frames (see [6.4 Call Frame
+ Information](#call-frame-information)).
+
+ It is required for the evaluation of location list expressions to select
+ amongst multiple program location ranges. It is required for operations that
+ specify target architecture registers to support virtual unwinding of the
+ call stack (see [6.4 Call Frame Information](#call-frame-information)).
+
+ If specified:
+
+ - If the current call frame is the top call frame, it must be the current
+ target architecture program location.
+ - If the current call frame F is not the top call frame, it must be the
+ program location associated with the call site in the current caller frame
+ F that invoked the callee frame.
+ - Otherwise the result is undefined.
+
+5. <i>A current compilation unit</i>
+
+ The compilation unit debug information entry that contains the DWARF
+ expression being evaluated.
+
+ It is required for operations that reference debug information associated
+ with the same compilation unit, including indicating if such references use
+ the 32-bit or 64-bit DWARF format. It can also provide the default address
+ space address size if no current target architecture is specified.
+
+ <i>For example, the `DW_OP_constx` and `DW_OP_addrx` operations.</i>
+
+ <i>Note that this compilation unit may not be the same as the compilation
+ unit determined from the loaded code object corresponding to the current
+ program location. For example, the evaluation of the expression E associated
+ with a `DW_AT_location` attribute of the debug information entry operand of
+ the `DW_OP_call*` operations is evaluated with the compilation unit that
+ contains E and not the one that contains the `DW_OP_call*` operation
+ expression.</i>
+
+6. <i>A current target architecture</i>
+
+ The target architecture.
+
+ It is required for operations that specify target architecture specific
+ entities.
+
+ <i>For example, target architecture specific entities include DWARF register
+ identifiers, DWARF address space identifiers, the default address space, and
+ the address space address sizes.</i>
+
+ If specified:
+
+ - If the current thread is specified, then the current target architecture
+ must be the same as the target architecture of the current thread.
+ - If the current compilation unit is specified, then the current target
+ architecture default address space address size must be the same as the
+ `address_size` field in the header of the current compilation unit and any
+ associated entry in the `.debug_aranges` section.
+ - If the current program location is specified, then the current target
+ architecture must be the same as the target architecture of any line
+ number information entry (see [6.2 Line Number
+ Information](#line-number-information)) corresponding to the current
+ program location.
+ - If the current program location is specified, then the current target
+ architecture default address space address size must be the same as the
+ `address_size` field in the header of any entry corresponding to the
+ current program location in the `.debug_addr`, `.debug_line`,
+ `.debug_rnglists`, `.debug_rnglists.dwo`, `.debug_loclists`, and
+ `.debug_loclists.dwo` sections.
+ - Otherwise the result is undefined.
+
+7. <i>A current object</i>
+
+ The location description of a program object.
+
+ It is required for the `DW_OP_push_object_address` operation.
+
+ <i>For example, the `DW_AT_data_location` attribute on type debug
+ information entries specifies the program object corresponding to a runtime
+ descriptor as the current object when it evaluates its associated
+ expression.</i>
+
+ The result is undefined if the location descriptor is invalid (see [3.5.3
+ DWARF Location Description](#dwarf-location-description)).
+
+8. <i>An initial stack</i>
+
+ This is a list of values or location descriptions that will be pushed on the
+ operation expression evaluation stack in the order provided before
+ evaluation of an operation expression starts.
+
+ Some debugger information entries have attributes that evaluate their DWARF
+ expression value with initial stack entries. In all other cases the initial
+ stack is empty.
+
+ The result is undefined if any location descriptors are invalid (see [3.5.3
+ DWARF Location Description](#dwarf-location-description)).
+
+If the evaluation requires a context element that is not specified, then the
+result of the evaluation is an error.
+
+<i>A DWARF expression for a location description may be able to be evaluated
+without a thread, call frame, program location, or architecture context. For
+example, the location of a global variable may be able to be evaluated without
+such context. If the expression evaluates with an error then it may indicate the
+variable has been optimized and so requires more context.</i>
+
+<i>The DWARF expression for call frame information (see [6.4 Call Frame
+Information](#call-frame-information)) operations are restricted to those
+that do not require the compilation unit context to be specified.</i>
+
+The DWARF is ill-formed if all the `address_size` fields in the headers of all
+the entries in the `.debug_info`, `.debug_addr`, `.debug_line`,
+`.debug_rnglists`, `.debug_rnglists.dwo`, `.debug_loclists`, and
+`.debug_loclists.dwo` sections corresponding to any given program location do
+not match.
+
+#### A.2.5.2 DWARF Expression Value
+
+A value has a type and a literal value. It can represent a literal value of any
+supported base type of the target architecture. The base type specifies the
+size, encoding, and endianity of the literal value.
+
+> NOTE: It may be desirable to add an implicit pointer base type encoding. It
+> would be used for the type of the value that is produced when the
+> `DW_OP_deref*` operation retrieves the full contents of an implicit pointer
+> location storage created by the `DW_OP_implicit_pointer` operation. The
+> literal value would record the debugging information entry and byte
+> displacement specified by the associated `DW_OP_implicit_pointer` operation.
+
+There is a distinguished base type termed the generic type, which is an integral
+type that has the size of an address in the target architecture default address
+space, a target architecture defined endianity, and unspecified signedness.
+
+<i>The generic type is the same as the unspecified type used for stack
+operations defined in DWARF Version 4 and before.</i>
+
+An integral type is a base type that has an encoding of `DW_ATE_signed`,
+`DW_ATE_signed_char`, `DW_ATE_unsigned`, `DW_ATE_unsigned_char`,
+`DW_ATE_boolean`, or any target architecture defined integral encoding in the
+inclusive range `DW_ATE_lo_user` to `DW_ATE_hi_user`.
+
+> NOTE: It is unclear if `DW_ATE_address` is an integral type. GDB does not seem
+> to consider it as integral.
+
+#### A.2.5.3 DWARF Location Description
+
+<i>Debugging information must provide consumers a way to find the location of
+program variables, determine the bounds of dynamic arrays and strings, and
+possibly to find the base address of a subprogram's call frame or the return
+address of a subprogram. Furthermore, to meet the needs of recent computer
+architectures and optimization techniques, debugging information must be able to
+describe the location of an object whose location changes over the object's
+lifetime, and may reside at multiple locations simultaneously during parts of an
+object's lifetime.</i>
+
+Information about the location of program objects is provided by location
+descriptions.
+
+Location descriptions can consist of one or more single location descriptions.
+
+A single location description specifies the location storage that holds a
+program object and a position within the location storage where the program
+object starts. The position within the location storage is expressed as a bit
+offset relative to the start of the location storage.
+
+A location storage is a linear stream of bits that can hold values. Each
+location storage has a size in bits and can be accessed using a zero-based bit
+offset. The ordering of bits within a location storage uses the bit numbering
+and direction conventions that are appropriate to the current language on the
+target architecture.
+
+There are five kinds of location storage:
+
+1. <i>memory location storage</i>
+
+ Corresponds to the target architecture memory address spaces.
+
+2. <i>register location storage</i>
+
+ Corresponds to the target architecture registers.
+
+3. <i>implicit location storage</i>
+
+ Corresponds to fixed values that can only be read.
+
+4. <i>undefined location storage</i>
+
+ Indicates no value is available and therefore cannot be read or written.
+
+5. <i>composite location storage</i>
+
+ Allows a mixture of these where some bits come from one location storage and
+ some from another location storage, or from disjoint parts of the same
+ location storage.
+
+> NOTE: It may be better to add an implicit pointer location storage kind used
+> by the `DW_OP_implicit_pointer` operation. It would specify the debugger
+> information entry and byte offset provided by the operations.
+
+<i>Location descriptions are a language independent representation of addressing
+rules.</i>
+
+- <i>They can be the result of evaluating a debugger information entry attribute
+ that specifies an operation expression of arbitrary complexity. In this usage
+ they can describe the location of an object as long as its lifetime is either
+ static or the same as the lexical block (see [3.5 Lexical Block
+ Entries](#lexical-block-entries)) that owns it, and it does not move during
+ its lifetime.</i>
+
+- <i>They can be the result of evaluating a debugger information entry attribute
+ that specifies a location list expression. In this usage they can describe the
+ location of an object that has a limited lifetime, changes its location during
+ its lifetime, or has multiple locations over part or all of its lifetime.</i>
+
+If a location description has more than one single location description, the
+DWARF expression is ill-formed if the object value held in each single location
+description's position within the associated location storage is not the same
+value, except for the parts of the value that are uninitialized.
+
+<i>A location description that has more than one single location description can
+only be created by a location list expression that has overlapping program
+location ranges, or certain expression operations that act on a location
+description that has more than one single location description. There are no
+operation expression operations that can directly create a location description
+with more than one single location description.</i>
+
+<i>A location description with more than one single location description can be
+used to describe objects that reside in more than one piece of storage at the
+same time. An object may have more than one location as a result of
+optimization. For example, a value that is only read may be promoted from memory
+to a register for some region of code, but later code may revert to reading the
+value from memory as the register may be used for other purposes. For the code
+region where the value is in a register, any change to the object value must be
+made in both the register and the memory so both regions of code will read the
+updated value.</i>
+
+<i>A consumer of a location description with more than one single location
+description can read the object's value from any of the single location
+descriptions (since they all refer to location storage that has the same value),
+but must write any changed value to all the single location descriptions.</i>
+
+Updating a location description L by a bit offset B is defined as adding the
+value of B to the bit offset of each single location description SL of L. It is
+an evaluation error if the updated bit offset of any SL is less than 0 or
+greater than or equal to the size of the location storage specified by SL.
+
+The evaluation of an expression may require context elements to create a
+location description. If such a location description is accessed, the storage it
+denotes is that associated with the context element values specified when the
+location description was created, which may differ from the context at the time
+it is accessed.
+
+<i>For example, creating a register location description requires the thread
+context: the location storage is for the specified register of that thread.
+Creating a memory location description for an address space may required a
+thread context: the location storage is the memory associated with that
+thread.</i>
+
+If any of the context elements required to create a location description change,
+the location description becomes invalid and accessing it is undefined.
+
+<i>Examples of context that can invalidate a location description are:</i>
+
+- <i>The thread context is required and execution causes the thread to
+ terminate.</i>
+- <i>The call frame context is required and further execution causes the call
+ frame to return to the calling frame.</i>
+- <i>The program location is required and further execution of the thread
+ occurs. That could change the location list entry or call frame information
+ entry that applies.</i>
+- <i>An operation uses call frame information:</i>
+ - <i>Any of the frames used in the virtual call frame unwinding return.</i>
+ - <i>The top call frame is used, the program location is used to select the
+ call frame information entry, and further execution of the thread
+ occurs.</i>
+
+<i>A DWARF expression can be used to compute a location description for an
+object. A subsequent DWARF expression evaluation can be given the object
+location description as the object context or initial stack context to compute a
+component of the object. The final result is undefined if the object location
+description becomes invalid between the two expression evaluations.</i>
+
+A change of a thread's program location may not make a location description
+invalid, yet may still render it as no longer meaningful. Accessing such a
+location description, or using it as the object context or initial stack context
+of an expression evaluation, may produce an undefined result.
+
+<i>For example, a location description may specify a register that no longer
+holds the intended program object after a program location change. One way to
+avoid such problems is to recompute location descriptions associated with
+threads when their program locations change.</i>
+
+#### A.2.5.4 DWARF Operation Expressions
+
+An operation expression is comprised of a stream of operations, each consisting
+of an opcode followed by zero or more operands. The number of operands is
+implied by the opcode.
+
+Operations represent a postfix operation on a simple stack machine. Each stack
+entry can hold either a value or a location description. Operations can act on
+entries on the stack, including adding entries and removing entries. If the kind
+of a stack entry does not match the kind required by the operation and is not
+implicitly convertible to the required kind (see [2.5.4.4.3 Memory Location
+Description Operations](#memory-location-description-operations)), then
+the DWARF operation expression is ill-formed.
+
+Evaluation of an operation expression starts with an empty stack on which the
+entries from the initial stack provided by the context are pushed in the order
+provided. Then the operations are evaluated, starting with the first operation
+of the stream. Evaluation continues until either an operation has an evaluation
+error, or until one past the last operation of the stream is reached.
+
+The result of the evaluation is:
+
+- If an operation has an evaluation error, or an operation evaluates an
+ expression that has an evaluation error, then the result is an evaluation
+ error.
+- If the current result kind specifies a location description, then:
+ - If the stack is empty, the result is a location description with one
+ undefined location description.
+
+ <i>This rule is for backwards compatibility with DWARF Version 5 which uses
+ an empty operation expression for this purpose.</i>
+
+ - If the top stack entry is a location description, or can be converted to one
+ (see [2.5.4.4.3 Memory Location Description
+ Operations](#memory-location-description-operations)), then the result
+ is that, possibly converted, location description. Any other entries on the
+ stack are discarded.
+ - Otherwise the DWARF expression is ill-formed.
+
+ > NOTE: Could define this case as returning an implicit location description
+ > as if the `DW_OP_implicit` operation is performed.
+
+- If the current result kind specifies a value, then:
+ - If the top stack entry is a value, or can be converted to one (see
+ [2.5.4.4.3 Memory Location Description
+ Operations](#memory-location-description-operations)), then the result is
+ that, possibly converted, value. Any other entries on the stack are
+ discarded.
+ - Otherwise the DWARF expression is ill-formed.
+- If the current result kind is not specified, then:
+ - If the stack is empty, the result is a location description with one
+ undefined location description.
+
+ <i>This rule is for backwards compatibility with DWARF Version 5 which uses
+ an empty operation expression for this purpose.</i>
+
+ > NOTE: This rule is consistent with the rule above for when a location
+ > description is requested. However, GDB appears to report this as an error
+ > and no GDB tests appear to cause an empty stack for this case.
+
+ - Otherwise, the top stack entry is returned. Any other entries on the stack
+ are discarded.
+
+An operation expression is encoded as a byte block with some form of prefix that
+specifies the byte count. It can be used:
+
+- as the value of a debugging information entry attribute that is encoded using
+ class `exprloc` (see [7.5.5 Classes and Forms](#classes-and-forms)),
+- as the operand to certain operation expression operations,
+- as the operand to certain call frame information operations (see [6.4 Call
+ Frame Information](#call-frame-information)),
+- and in location list entries (see [2.5.5 DWARF Location List
+ Expressions](#dwarf-location-list-expressions)).
+
+##### A.2.5.4.1 Stack Operations
+
+> NOTE: This section replaces DWARF Version 5 section 2.5.1.3.
+
+The following operations manipulate the DWARF stack. Operations that index the
+stack assume that the top of the stack (most recently added entry) has index 0.
+They allow the stack entries to be either a value or location description.
+
+If any stack entry accessed by a stack operation is an incomplete composite
+location description (see [2.5.4.4.6 Composite Location Description
+Operations](#composite-location-description-operations)), then the DWARF
+expression is ill-formed.
+
+> NOTE: These operations now support stack entries that are values and location
+> descriptions.
+
+> NOTE: If it is desired to also make them work with incomplete composite
+> location descriptions, then would need to define that the composite location
+> storage specified by the incomplete composite location description is also
+> replicated when a copy is pushed. This ensures that each copy of the
+> incomplete composite location description can update the composite location
+> storage they specify independently.
+
+1. `DW_OP_dup`
+
+ `DW_OP_dup` duplicates the stack entry at the top of the stack.
+
+2. `DW_OP_drop`
+
+ `DW_OP_drop` pops the stack entry at the top of the stack and discards it.
+
+3. `DW_OP_pick`
+
+ `DW_OP_pick` has a single unsigned 1-byte operand that represents an index
+ I. A copy of the stack entry with index I is pushed onto the stack.
+
+4. `DW_OP_over`
+
+ `DW_OP_over` pushes a copy of the entry with index 1.
+
+ <i>This is equivalent to a `DW_OP_pick 1` operation.</i>
+
+5. `DW_OP_swap`
+
+ `DW_OP_swap` swaps the top two stack entries. The entry at the top of the
+ stack becomes the second stack entry, and the second stack entry becomes the
+ top of the stack.
+
+6. `DW_OP_rot`
+
+ `DW_OP_rot` rotates the first three stack entries. The entry at the top of
+ the stack becomes the third stack entry, the second entry becomes the top of
+ the stack, and the third entry becomes the second entry.
+
+##### A.2.5.4.2 Control Flow Operations
+
+> NOTE: This section replaces DWARF Version 5 section 2.5.1.5.
+
+The following operations provide simple control of the flow of a DWARF operation
+expression.
+
+1. `DW_OP_nop`
+
+ `DW_OP_nop` is a place holder. It has no effect on the DWARF stack entries.
+
+2. `DW_OP_le`, `DW_OP_ge`, `DW_OP_eq`, `DW_OP_lt`, `DW_OP_gt`,
+ `DW_OP_ne`
+
+ > NOTE: The same as in DWARF Version 5 section 2.5.1.5.
+
+3. `DW_OP_skip`
+
+ `DW_OP_skip` is an unconditional branch. Its single operand is a 2-byte
+ signed integer constant. The 2-byte constant is the number of bytes of the
+ DWARF expression to skip forward or backward from the current operation,
+ beginning after the 2-byte constant.
+
+ If the updated position is at one past the end of the last operation, then
+ the operation expression evaluation is complete.
+
+ Otherwise, the DWARF expression is ill-formed if the updated operation
+ position is not in the range of the first to last operation inclusive, or
+ not at the start of an operation.
+
+4. `DW_OP_bra`
+
+ `DW_OP_bra` is a conditional branch. Its single operand is a 2-byte signed
+ integer constant. This operation pops the top of stack. If the value popped
+ is not the constant 0, the 2-byte constant operand is the number of bytes of
+ the DWARF operation expression to skip forward or backward from the current
+ operation, beginning after the 2-byte constant.
+
+ If the updated position is at one past the end of the last operation, then
+ the operation expression evaluation is complete.
+
+ Otherwise, the DWARF expression is ill-formed if the updated operation
+ position is not in the range of the first to last operation inclusive, or
+ not at the start of an operation.
+
+5. `DW_OP_call2, DW_OP_call4, DW_OP_call_ref`
+
+ `DW_OP_call2`, `DW_OP_call4`, and `DW_OP_call_ref` perform DWARF procedure
+ calls during evaluation of a DWARF expression.
+
+ `DW_OP_call2` and `DW_OP_call4`, have one operand that is, respectively, a
+ 2-byte or 4-byte unsigned offset DR that represents the byte offset of a
+ debugging information entry D relative to the beginning of the current
+ compilation unit.
+
+ `DW_OP_call_ref` has one operand that is a 4-byte unsigned value in the
+ 32-bit DWARF format, or an 8-byte unsigned value in the 64-bit DWARF format,
+ that represents the byte offset DR of a debugging information entry D
+ relative to the beginning of the `.debug_info` section that contains the
+ current compilation unit. D may not be in the current compilation unit.
+
+ > NOTE: DWARF Version 5 states that DR can be an offset in a `.debug_info`
+ > section other than the one that contains the current compilation unit. It
+ > states that relocation of references from one executable or shared object
+ > file to another must be performed by the consumer. But given that DR is
+ > defined as an offset in a `.debug_info` section this seems impossible. If
+ > DR was defined as an implementation defined value, then the consumer could
+ > choose to interpret the value in an implementation defined manner to
+ > reference a debug information in another executable or shared object.
+ >
+ > In ELF the `.debug_info` section is in a non-`PT_LOAD` segment so standard
+ > dynamic relocations cannot be used. But even if they were loaded segments
+ > and dynamic relocations were used, DR would need to be the address of D,
+ > not an offset in a `.debug_info` section. That would also need DR to be
+ > the size of a global address. So it would not be possible to use the
+ > 32-bit DWARF format in a 64-bit global address space. In addition, the
+ > consumer would need to determine what executable or shared object the
+ > relocated address was in so it could determine the containing compilation
+ > unit.
+ >
+ > GDB only interprets DR as an offset in the `.debug_info` section that
+ > contains the current compilation unit.
+ >
+ > This comment also applies to `DW_OP_implicit_pointer`.
+
+ <i>Operand interpretation of `DW_OP_call2`, `DW_OP_call4`, and
+ `DW_OP_call_ref` is exactly like that for `DW_FORM_ref2`, `DW_FORM_ref4`,
+ and `DW_FORM_ref_addr`, respectively.</i>
+
+ The call operation is evaluated by:
+
+ - If D has a `DW_AT_location` attribute that is encoded as a `exprloc` that
+ specifies an operation expression E, then execution of the current
+ operation expression continues from the first operation of E. Execution
+ continues until one past the last operation of E is reached, at which
+ point execution continues with the operation following the call operation.
+ The operations of E are evaluated with the same current context, except
+ current compilation unit is the one that contains D and the stack is the
+ same as that being used by the call operation. After the call operation
+ has been evaluated, the stack is therefore as it is left by the evaluation
+ of the operations of E. Since E is evaluated on the same stack as the call
+ operation, E can use, and/or remove entries already on the stack, and can
+ add new entries to the stack.
+
+ <i>Values on the stack at the time of the call may be used as parameters
+ by the called expression and values left on the stack by the called
+ expression may be used as return values by prior agreement between the
+ calling and called expressions.</i>
+
+ - If D has a `DW_AT_location` attribute that is encoded as a `loclist` or
+ `loclistsptr`, then the specified location list expression E is evaluated.
+ The evaluation of E uses the current context, except the result kind is a
+ location description, the compilation unit is the one that contains D, and
+ the initial stack is empty. The location description result is pushed on
+ the stack.
+
+ > NOTE: This rule avoids having to define how to execute a matched
+ > location list entry operation expression on the same stack as the call
+ > when there are multiple matches. But it allows the call to obtain the
+ > location description for a variable or formal parameter which may use a
+ > location list expression.
+ >
+ > An alternative is to treat the case when D has a `DW_AT_location`
+ > attribute that is encoded as a `loclist` or `loclistsptr`, and the
+ > specified location list expression E' matches a single location list
+ > entry with operation expression E, the same as the `exprloc` case and
+ > evaluate on the same stack.
+ >
+ > But this is not attractive as if the attribute is for a variable that
+ > happens to end with a non-singleton stack, it will not simply put a
+ > location description on the stack. Presumably the intent of using
+ > `DW_OP_call*` on a variable or formal parameter debugger information
+ > entry is to push just one location description on the stack. That
+ > location description may have more than one single location description.
+ >
+ > The previous rule for `exprloc` also has the same problem, as normally a
+ > variable or formal parameter location expression may leave multiple
+ > entries on the stack and only return the top entry.
+ >
+ > GDB implements `DW_OP_call*` by always executing E on the same stack. If
+ > the location list has multiple matching entries, it simply picks the
+ > first one and ignores the rest. This seems fundamentally at odds with
+ > the desire to support multiple places for variables.
+ >
+ > So, it feels like `DW_OP_call*` should both support pushing a location
+ > description on the stack for a variable or formal parameter, and also
+ > support being able to execute an operation expression on the same stack.
+ > Being able to specify a different operation expression for different
+ > program locations seems a desirable feature to retain.
+ >
+ > A solution to that is to have a distinct `DW_AT_proc` attribute for the
+ > `DW_TAG_dwarf_procedure` debugging information entry. Then the
+ > `DW_AT_location` attribute expression is always executed separately and
+ > pushes a location description (that may have multiple single location
+ > descriptions), and the `DW_AT_proc` attribute expression is always
+ > executed on the same stack and can leave anything on the stack.
+ >
+ > The `DW_AT_proc` attribute could have the new classes `exprproc`,
+ > `loclistproc`, and `loclistsptrproc` to indicate that the expression is
+ > executed on the same stack. `exprproc` is the same encoding as
+ > `exprloc`. `loclistproc` and `loclistsptrproc` are the same encoding as
+ > their non-`proc` counterparts, except the DWARF is ill-formed if the
+ > location list does not match exactly one location list entry and a
+ > default entry is required. These forms indicate explicitly that the
+ > matched single operation expression must be executed on the same stack.
+ > This is better than ad hoc special rules for `loclistproc` and
+ > `loclistsptrproc` which are currently clearly defined to always return a
+ > location description. The producer then explicitly indicates the intent
+ > through the attribute classes.
+ >
+ > Such a change would be a breaking change for how GDB implements
+ > `DW_OP_call*`. However, are the breaking cases actually occurring in
+ > practice? GDB could implement the current approach for DWARF Version 5,
+ > and the new semantics for DWARF Version 6 which has been done for some
+ > other features.
+ >
+ > Another option is to limit the execution to be on the same stack only to
+ > the evaluation of an expression E that is the value of a
+ > `DW_AT_location` attribute of a `DW_TAG_dwarf_procedure` debugging
+ > information entry. The DWARF would be ill-formed if E is a location list
+ > expression that does not match exactly one location list entry. In all
+ > other cases the evaluation of an expression E that is the value of a
+ > `DW_AT_location` attribute would evaluate E with the current context,
+ > except the result kind is a location description, the compilation unit
+ > is the one that contains D, and the initial stack is empty. The location
+ > description result is pushed on the stack.
+
+ - If D has a `DW_AT_const_value` attribute with a value V, then it is as if
+ a `DW_OP_implicit_value V` operation was executed.
+
+ <i>This allows a call operation to be used to compute the location
+ description for any variable or formal parameter regardless of whether the
+ producer has optimized it to a constant. This is consistent with the
+ `DW_OP_implicit_pointer` operation.</i>
+
+ > NOTE: Alternatively, could deprecate using `DW_AT_const_value` for
+ > `DW_TAG_variable` and `DW_TAG_formal_parameter` debugger information
+ > entries that are constants and instead use `DW_AT_location` with an
+ > operation expression that results in a location description with one
+ > implicit location description. Then this rule would not be required.
+
+ - Otherwise, there is no effect and no changes are made to the stack.
+
+ > NOTE: In DWARF Version 5, if D does not have a `DW_AT_location` then
+ > `DW_OP_call*` is defined to have no effect. It is unclear that this is
+ > the right definition as a producer should be able to rely on using
+ > `DW_OP_call*` to get a location description for any
+ > non-`DW_TAG_dwarf_procedure` debugging information entries. Also, the
+ > producer should not be creating DWARF with `DW_OP_call*` to a
+ > `DW_TAG_dwarf_procedure` that does not have a `DW_AT_location`
+ > attribute. So, should this case be defined as an ill-formed DWARF
+ > expression?
+
+ <i>The `DW_TAG_dwarf_procedure` debugging information entry can be used to
+ define DWARF procedures that can be called.</i>
+
+##### A.2.5.4.3 Value Operations
+
+This section describes the operations that push values on the stack.
+
+Each value stack entry has a type and a literal value. It can represent a
+literal value of any supported base type of the target architecture. The base
+type specifies the size, encoding, and endianity of the literal value.
+
+The base type of value stack entries can be the distinguished generic type.
+
+###### A.2.5.4.3.1 Literal Operations
+
+> NOTE: This section replaces DWARF Version 5 section 2.5.1.1.
+
+The following operations all push a literal value onto the DWARF stack.
+
+Operations other than `DW_OP_const_type` push a value V with the generic type.
+If V is larger than the generic type, then V is truncated to the generic type
+size and the low-order bits used.
+
+1. `DW_OP_lit0`, `DW_OP_lit1`, ..., `DW_OP_lit31`
+
+ `DW_OP_lit<N>` operations encode an unsigned literal value N from 0 through
+ 31, inclusive. They push the value N with the generic type.
+
+2. `DW_OP_const1u`, `DW_OP_const2u`, `DW_OP_const4u`, `DW_OP_const8u`
+
+ `DW_OP_const<N>u` operations have a single operand that is a 1, 2, 4, or
+ 8-byte unsigned integer constant U, respectively. They push the value U with
+ the generic type.
+
+3. `DW_OP_const1s`, `DW_OP_const2s`, `DW_OP_const4s`, `DW_OP_const8s`
+
+ `DW_OP_const<N>s` operations have a single operand that is a 1, 2, 4, or
+ 8-byte signed integer constant S, respectively. They push the value S with
+ the generic type.
+
+4. `DW_OP_constu`
+
+ `DW_OP_constu` has a single unsigned LEB128 integer operand N. It pushes the
+ value N with the generic type.
+
+5. `DW_OP_consts`
+
+ `DW_OP_consts` has a single signed LEB128 integer operand N. It pushes the
+ value N with the generic type.
+
+6. `DW_OP_constx`
+
+ `DW_OP_constx` has a single unsigned LEB128 integer operand that represents
+ a zero-based index into the `.debug_addr` section relative to the value of
+ the `DW_AT_addr_base` attribute of the associated compilation unit. The
+ value N in the `.debug_addr` section has the size of the generic type. It
+ pushes the value N with the generic type.
+
+ <i>The `DW_OP_constx` operation is provided for constants that require
+ link-time relocation but should not be interpreted by the consumer as a
+ relocatable address (for example, offsets to thread-local storage).</i>
+
+7. `DW_OP_const_type`
+
+ `DW_OP_const_type` has three operands. The first is an unsigned LEB128
+ integer DR that represents the byte offset of a debugging information entry
+ D relative to the beginning of the current compilation unit, that provides
+ the type T of the constant value. The second is a 1-byte unsigned integral
+ constant S. The third is a block of bytes B, with a length equal to S.
+
+ TS is the bit size of the type T. The least significant TS bits of B are
+ interpreted as a value V of the type D. It pushes the value V with the type
+ D.
+
+ The DWARF is ill-formed if D is not a `DW_TAG_base_type` debugging
+ information entry in the current compilation unit, or if TS divided by 8
+ (the byte size) and rounded up to a whole number is not equal to S.
+
+ <i>While the size of the byte block B can be inferred from the type D
+ definition, it is encoded explicitly into the operation so that the
+ operation can be parsed easily without reference to the `.debug_info`
+ section.</i>
+
+###### A.2.5.4.3.2 Arithmetic and Logical Operations
+
+> NOTE: This section is the same as DWARF Version 5 section 2.5.1.4.
+
+###### A.2.5.4.3.3 Type Conversion Operations
+
+> NOTE: This section is the same as DWARF Version 5 section 2.5.1.6.
+
+###### A.2.5.4.3.4 Special Value Operations
+
+> NOTE: This section replaces parts of DWARF Version 5 sections 2.5.1.2,
+ 2.5.1.3, and 2.5.1.7.
+
+There are these special value operations currently defined:
+
+1. `DW_OP_regval_type`
+
+ `DW_OP_regval_type` has two operands. The first is an unsigned LEB128
+ integer that represents a register number R. The second is an unsigned
+ LEB128 integer DR that represents the byte offset of a debugging information
+ entry D relative to the beginning of the current compilation unit, that
+ provides the type T of the register value.
+
+ The operation is equivalent to performing `DW_OP_regx R; DW_OP_deref_type
+ DR`.
+
+ > NOTE: Should DWARF allow the type T to be a larger size than the size of
+ > the register R? Restricting a larger bit size avoids any issue of
+ > conversion as the, possibly truncated, bit contents of the register is
+ > simply interpreted as a value of T. If a conversion is wanted it can be
+ > done explicitly using a `DW_OP_convert` operation.
+ >
+ > GDB has a per register hook that allows a target specific conversion on a
+ > register by register basis. It defaults to truncation of bigger registers.
+ > Removing use of the target hook does not cause any test failures in common
+ > architectures. If the compiler for a target architecture did want some
+ > form of conversion, including a larger result type, it could always
+ > explicitly used the `DW_OP_convert` operation.
+ >
+ > If T is a larger type than the register size, then the default GDB
+ > register hook reads bytes from the next register (or reads out of bounds
+ > for the last register!). Removing use of the target hook does not cause
+ > any test failures in common architectures (except an illegal hand written
+ > assembly test). If a target architecture requires this behavior, these
+ > extensions allow a composite location description to be used to combine
+ > multiple registers.
+
+2. `DW_OP_deref`
+
+ S is the bit size of the generic type divided by 8 (the byte size) and
+ rounded up to a whole number. DR is the offset of a hypothetical debug
+ information entry D in the current compilation unit for a base type of the
+ generic type.
+
+ The operation is equivalent to performing `DW_OP_deref_type S, DR`.
+
+3. `DW_OP_deref_size`
+
+ `DW_OP_deref_size` has a single 1-byte unsigned integral constant that
+ represents a byte result size S.
+
+ TS is the smaller of the generic type bit size and S scaled by 8 (the byte
+ size). If TS is smaller than the generic type bit size then T is an unsigned
+ integral type of bit size TS, otherwise T is the generic type. DR is the
+ offset of a hypothetical debug information entry D in the current
+ compilation unit for a base type T.
+
+ > NOTE: Truncating the value when S is larger than the generic type matches
+ > what GDB does. This allows the generic type size to not be an integral
+ > byte size. It does allow S to be arbitrarily large. Should S be restricted
+ > to the size of the generic type rounded up to a multiple of 8?
+
+ The operation is equivalent to performing `DW_OP_deref_type S, DR`, except
+ if T is not the generic type, the value V pushed is zero-extended to the
+ generic type bit size and its type changed to the generic type.
+
+4. `DW_OP_deref_type`
+
+ `DW_OP_deref_type` has two operands. The first is a 1-byte unsigned integral
+ constant S. The second is an unsigned LEB128 integer DR that represents the
+ byte offset of a debugging information entry D relative to the beginning of
+ the current compilation unit, that provides the type T of the result value.
+
+ TS is the bit size of the type T.
+
+ <i>While the size of the pushed value V can be inferred from the type T, it
+ is encoded explicitly as the operand S so that the operation can be parsed
+ easily without reference to the `.debug_info` section.</i>
+
+ > NOTE: It is unclear why the operand S is needed. Unlike
+ > `DW_OP_const_type`, the size is not needed for parsing. Any evaluation
+ > needs to get the base type T to push with the value to know its encoding
+ > and bit size.
+
+ It pops one stack entry that must be a location description L.
+
+ A value V of TS bits is retrieved from the location storage LS specified by
+ one of the single location descriptions SL of L.
+
+ <i>If L, or the location description of any composite location description
+ part that is a subcomponent of L, has more than one single location
+ description, then any one of them can be selected as they are required to
+ all have the same value. For any single location description SL, bits are
+ retrieved from the associated storage location starting at the bit offset
+ specified by SL. For a composite location description, the retrieved bits
+ are the concatenation of the N bits from each composite location part PL,
+ where N is limited to the size of PL.</i>
+
+ V is pushed on the stack with the type T.
+
+ > NOTE: This definition makes it an evaluation error if L is a register
+ > location description that has less than TS bits remaining in the register
+ > storage. Particularly since these extensions extend location descriptions
+ > to have a bit offset, it would be odd to define this as performing sign
+ > extension based on the type, or be target architecture dependent, as the
+ > number of remaining bits could be any number. This matches the GDB
+ > implementation for `DW_OP_deref_type`.
+ >
+ > These extensions define `DW_OP_*breg*` in terms of `DW_OP_regval_type`.
+ > `DW_OP_regval_type` is defined in terms of `DW_OP_regx`, which uses a 0
+ > bit offset, and `DW_OP_deref_type`. Therefore, it requires the register
+ > size to be greater or equal to the address size of the address space. This
+ > matches the GDB implementation for `DW_OP_*breg*`.
+
+ The DWARF is ill-formed if D is not in the current compilation unit, D is
+ not a `DW_TAG_base_type` debugging information entry, or if TS divided by 8
+ (the byte size) and rounded up to a whole number is not equal to S.
+
+ > NOTE: This definition allows the base type to be a bit size since there
+ > seems no reason to restrict it.
+
+ It is an evaluation error if any bit of the value is retrieved from the
+ undefined location storage or the offset of any bit exceeds the size of the
+ location storage LS specified by any single location description SL of L.
+
+ See [2.5.4.4.5 Implicit Location Description
+ Operations](#implicit-location-description-operations) for special
+ rules concerning implicit location descriptions created by the
+ `DW_OP_implicit_pointer` operation.
+
+5. `DW_OP_xderef`
+
+ `DW_OP_xderef` pops two stack entries. The first must be an integral type
+ value that represents an address A. The second must be an integral type
+ value that represents a target architecture specific address space
+ identifier AS.
+
+ The address size S is defined as the address bit size of the target
+ architecture specific address space that corresponds to AS.
+
+ A is adjusted to S bits by zero extending if necessary, and then treating
+ the least significant S bits as an unsigned value A'.
+
+ It creates a location description L with one memory location description SL.
+ SL specifies the memory location storage LS that corresponds to AS with a
+ bit offset equal to A' scaled by 8 (the byte size).
+
+ If AS is an address space that is specific to context elements, then LS
+ corresponds to the location storage associated with the current context.
+
+ <i>For example, if AS is for per thread storage then LS is the location
+ storage for the current thread. Therefore, if L is accessed by an operation,
+ the location storage selected when the location description was created is
+ accessed, and not the location storage associated with the current context
+ of the access operation.</i>
+
+ The DWARF expression is ill-formed if AS is not one of the values defined by
+ the target architecture specific `DW_ASPACE_*` values.
+
+ The operation is equivalent to popping A and AS, pushing L, and then
+ performing `DW_OP_deref`. The value V retrieved is left on the stack with
+ the generic type.
+
+6. `DW_OP_xderef_size`
+
+ `DW_OP_xderef_size` has a single 1-byte unsigned integral constant that
+ represents a byte result size S.
+
+ It pops two stack entries. The first must be an integral type value
+ that represents an address A. The second must be an integral type
+ value that represents a target architecture specific address space
+ identifier AS.
+
+ It creates a location description L as described for `DW_OP_xderef`.
+
+ The operation is equivalent to popping A and AS, pushing L, and then
+ performing `DW_OP_deref_size S` . The zero-extended value V retrieved is
+ left on the stack with the generic type.
+
+7. `DW_OP_xderef_type`
+
+ `DW_OP_xderef_type` has two operands. The first is a 1-byte unsigned
+ integral constant S. The second operand is an unsigned LEB128 integer DR
+ that represents the byte offset of a debugging information entry D relative
+ to the beginning of the current compilation unit, that provides the type T
+ of the result value.
+
+ It pops two stack entries. The first must be an integral type value that
+ represents an address A. The second must be an integral type value that
+ represents a target architecture specific address space identifier AS.
+
+ It creates a location description L as described for `DW_OP_xderef`.
+
+ The operation is equivalent to popping A and AS, pushing L, and then
+ performing `DW_OP_deref_type DR` . The value V retrieved is left on the
+ stack with the type T.
+
+8. `DW_OP_entry_value` <i>Deprecated</i>
+
+ `DW_OP_entry_value` pushes the value of an expression that is evaluated in
+ the context of the calling frame.
+
+ <i>It may be used to determine the value of arguments on entry to the
+ current call frame provided they are not clobbered.</i>
+
+ It has two operands. The first is an unsigned LEB128 integer S. The second
+ is a block of bytes, with a length equal S, interpreted as a DWARF operation
+ expression E.
+
+ E is evaluated with the current context, except the result kind is
+ unspecified, the call frame is the one that called the current frame, the
+ program location is the call site in the calling frame, the object is
+ unspecified, and the initial stack is empty. The calling frame information
+ is obtained by virtually unwinding the current call frame using the call
+ frame information (see [6.4 Call Frame
+ Information](#call-frame-information)).
+
+ If the result of E is a location description L (see [2.5.4.4.4 Register
+ Location Description
+ Operations](#register-location-description-operations)), and the last
+ operation executed by E is a `DW_OP_reg*` for register R with a target
+ architecture specific base type of T, then the contents of the register are
+ retrieved as if a `DW_OP_deref_type DR` operation was performed where DR is
+ the offset of a hypothetical debug information entry in the current
+ compilation unit for T. The resulting value V s pushed on the stack.
+
+ <i>Using `DW_OP_reg*` provides a more compact form for the case where the
+ value was in a register on entry to the subprogram.</i>
+
+ > NOTE: It is unclear how this provides a more compact expression, as
+ > `DW_OP_regval_type` could be used which is marginally larger.
+
+ If the result of E is a value V, then V is pushed on the stack.
+
+ Otherwise, the DWARF expression is ill-formed.
+
+ <i>The `DW_OP_entry_value` operation is deprecated as its main usage is
+ provided by other means. DWARF Version 5 added the
+ `DW_TAG_call_site_parameter` debugger information entry for call sites that
+ has `DW_AT_call_value`, `DW_AT_call_data_location`, and
+ `DW_AT_call_data_value` attributes that provide DWARF expressions to compute
+ actual parameter values at the time of the call, and requires the producer
+ to ensure the expressions are valid to evaluate even when virtually
+ unwound.</i>
+
+ > NOTE: GDB only implements `DW_OP_entry_value` when E is exactly
+ > `DW_OP_reg*` or `DW_OP_breg*; DW_OP_deref*`.
+
+##### A.2.5.4.4 Location Description Operations
+
+This section describes the operations that push location descriptions on the
+stack.
+
+###### A.2.5.4.4.1 General Location Description Operations
+
+> NOTE: This section replaces part of DWARF Version 5 section 2.5.1.3.
+
+1. `DW_OP_push_object_address`
+
+ `DW_OP_push_object_address` pushes the location description L of the current
+ object.
+
+ <i>This object may correspond to an independent variable that is part of a
+ user presented expression that is being evaluated. The object location
+ description may be determined from the variable's own debugging information
+ entry or it may be a component of an array, structure, or class whose
+ address has been dynamically determined by an earlier step during user
+ expression evaluation.</i>
+
+ <i>This operation provides explicit functionality (especially for arrays
+ involving descriptors) that is analogous to the implicit push of the base
+ location description of a structure prior to evaluation of a
+ `DW_AT_data_member_location` to access a data member of a structure.</i>
+
+ > NOTE: This operation could be removed and the object location description
+ > specified as the initial stack as for `DW_AT_data_member_location`.
+ >
+ > Or this operation could be used instead of needing to specify an initial
+ > stack. The latter approach is more composable as access to the object may
+ > be needed at any point of the expression, and passing it as the initial
+ > stack requires the entire expression to be aware where on the stack it is.
+ > If this were done, ``DW_AT_use_location`` would require a
+ > ``DW_OP_push_object2_address`` operation for the second object.
+ >
+ > Or a more general way to pass an arbitrary number of arguments in and an
+ > operation to get the Nth one such as ``DW_OP_arg N``. A vector of
+ > arguments would then be passed in the expression context rather than an
+ > initial stack. This could also resolve the issues with ``DW_OP_call*`` by
+ > allowing a specific number of arguments passed in and returned to be
+ > specified. The ``DW_OP_call*`` operation could then always execute on a
+ > separate stack: the number of arguments would be specified in a new call
+ > operation and taken from the callers stack, and similarly the number of
+ > return results specified and copied from the called stack back to the
+ > callee stack when the called expression was complete.
+ >
+ > The only attribute that specifies a current object is
+ > `DW_AT_data_location` so the non-normative text seems to overstate how
+ > this is being used. Or are there other attributes that need to state they
+ > pass an object?
+
+###### A.2.5.4.4.2 Undefined Location Description Operations
+
+> NOTE: This section replaces DWARF Version 5 section 2.6.1.1.1.
+
+<i>The undefined location storage represents a piece or all of an object that is
+present in the source but not in the object code (perhaps due to optimization).
+Neither reading nor writing to the undefined location storage is meaningful.</i>
+
+An undefined location description specifies the undefined location storage.
+There is no concept of the size of the undefined location storage, nor of a bit
+offset for an undefined location description. The `DW_OP_*piece` operations can
+implicitly specify an undefined location description, allowing any size and
+offset to be specified, and results in a part with all undefined bits.
+
+###### A.2.5.4.4.3 Memory Location Description Operations
+
+> NOTE: This section replaces parts of DWARF Version 5 section 2.5.1.1, 2.5.1.2,
+> 2.5.1.3, and 2.6.1.1.2.
+
+Each of the target architecture specific address spaces has a corresponding
+memory location storage that denotes the linear addressable memory of that
+address space. The size of each memory location storage corresponds to the range
+of the addresses in the corresponding address space.
+
+<i>It is target architecture defined how address space location storage maps to
+target architecture physical memory. For example, they may be independent
+memory, or more than one location storage may alias the same physical memory
+possibly at different offsets and with different interleaving. The mapping may
+also be dictated by the source language address classes.</i>
+
+A memory location description specifies a memory location storage. The bit
+offset corresponds to a bit position within a byte of the memory. Bits accessed
+using a memory location description, access the corresponding target
+architecture memory starting at the bit position within the byte specified by
+the bit offset.
+
+A memory location description that has a bit offset that is a multiple of 8 (the
+byte size) is defined to be a byte address memory location description. It has a
+memory byte address A that is equal to the bit offset divided by 8.
+
+A memory location description that does not have a bit offset that is a multiple
+of 8 (the byte size) is defined to be a bit field memory location description.
+It has a bit position B equal to the bit offset modulo 8, and a memory byte
+address A equal to the bit offset minus B that is then divided by 8.
+
+The address space AS of a memory location description is defined to be the
+address space that corresponds to the memory location storage associated with
+the memory location description.
+
+A location description that is comprised of one byte address memory location
+description SL is defined to be a memory byte address location description. It
+has a byte address equal to A and an address space equal to AS of the
+corresponding SL.
+
+`DW_ASPACE_none` is defined as the target architecture default address space.
+
+If a stack entry is required to be a location description, but it is a value V
+with the generic type, then it is implicitly converted to a location description
+L with one memory location description SL. SL specifies the memory location
+storage that corresponds to the target architecture default address space with a
+bit offset equal to V scaled by 8 (the byte size).
+
+> NOTE: If it is wanted to allow any integral type value to be implicitly
+> converted to a memory location description in the target architecture default
+> address space:
+>
+> > If a stack entry is required to be a location description, but is a value V
+> > with an integral type, then it is implicitly converted to a location
+> > description L with a one memory location description SL. If the type size of
+> > V is less than the generic type size, then the value V is zero extended to
+> > the size of the generic type. The least significant generic type size bits
+> > are treated as an unsigned value to be used as an address A. SL specifies
+> > memory location storage corresponding to the target architecture default
+> > address space with a bit offset equal to A scaled by 8 (the byte size).
+>
+> The implicit conversion could also be defined as target architecture specific.
+> For example, GDB checks if V is an integral type. If it is not it gives an
+> error. Otherwise, GDB zero-extends V to 64 bits. If the GDB target defines a
+> hook function, then it is called. The target specific hook function can modify
+> the 64-bit value, possibly sign extending based on the original value type.
+> Finally, GDB treats the 64-bit value V as a memory location address.
+
+If a stack entry is required to be a location description, but it is an implicit
+pointer value IPV with the target architecture default address space, then it is
+implicitly converted to a location description with one single location
+description specified by IPV. See [2.5.4.4.5 Implicit Location Description
+Operations](#implicit-location-description-operations).
+
+If a stack entry is required to be a value, but it is a location description L
+with one memory location description SL in the target architecture default
+address space with a bit offset B that is a multiple of 8, then it is implicitly
+converted to a value equal to B divided by 8 (the byte size) with the generic
+type.
+
+1. `DW_OP_addr`
+
+ `DW_OP_addr` has a single byte constant value operand, which has the size of
+ the generic type, that represents an address A.
+
+ It pushes a location description L with one memory location description SL
+ on the stack. SL specifies the memory location storage corresponding to the
+ target architecture default address space with a bit offset equal to A
+ scaled by 8 (the byte size).
+
+ <i>If the DWARF is part of a code object, then A may need to be relocated.
+ For example, in the ELF code object format, A must be adjusted by the
+ difference between the ELF segment virtual address and the virtual address
+ at which the segment is loaded.</i>
+
+2. `DW_OP_addrx`
+
+ `DW_OP_addrx` has a single unsigned LEB128 integer operand that represents a
+ zero-based index into the `.debug_addr` section relative to the value of the
+ `DW_AT_addr_base` attribute of the associated compilation unit. The address
+ value A in the `.debug_addr` section has the size of the generic type.
+
+ It pushes a location description L with one memory location description SL
+ on the stack. SL specifies the memory location storage corresponding to the
+ target architecture default address space with a bit offset equal to A
+ scaled by 8 (the byte size).
+
+ <i>If the DWARF is part of a code object, then A may need to be relocated.
+ For example, in the ELF code object format, A must be adjusted by the
+ difference between the ELF segment virtual address and the virtual address
+ at which the segment is loaded.</i>
+
+3. `DW_OP_form_tls_address`
+
+ `DW_OP_form_tls_address` pops one stack entry that must be an integral type
+ value and treats it as a thread-local storage address TA.
+
+ It pushes a location description L with one memory location description SL
+ on the stack. SL is the target architecture specific memory location
+ description that corresponds to the thread-local storage address TA.
+
+ The meaning of the thread-local storage address TA is defined by the
+ run-time environment. If the run-time environment supports multiple
+ thread-local storage blocks for a single thread, then the block
+ corresponding to the executable or shared library containing this DWARF
+ expression is used.
+
+ <i>Some implementations of C, C++, Fortran, and other languages support a
+ thread-local storage class. Variables with this storage class have distinct
+ values and addresses in distinct threads, much as automatic variables have
+ distinct values and addresses in each subprogram invocation. Typically,
+ there is a single block of storage containing all thread-local variables
+ declared in the main executable, and a separate block for the variables
+ declared in each shared library. Each thread-local variable can then be
+ accessed in its block using an identifier. This identifier is typically a
+ byte offset into the block and pushed onto the DWARF stack by one of the
+ `DW_OP_const*` operations prior to the `DW_OP_form_tls_address` operation.
+ Computing the address of the appropriate block can be complex (in some
+ cases, the compiler emits a function call to do it), and difficult to
+ describe using ordinary DWARF location descriptions. Instead of forcing
+ complex thread-local storage calculations into the DWARF expressions, the
+ `DW_OP_form_tls_address` allows the consumer to perform the computation
+ based on the target architecture specific run-time environment.</i>
+
+4. `DW_OP_call_frame_cfa`
+
+ `DW_OP_call_frame_cfa` pushes the location description L of the Canonical
+ Frame Address (CFA) of the current subprogram, obtained from the call frame
+ information on the stack. See [6.4 Call Frame
+ Information](#call-frame-information).
+
+ <i>Although the value of the `DW_AT_frame_base` attribute of the debugger
+ information entry corresponding to the current subprogram can be computed
+ using a location list expression, in some cases this would require an
+ extensive location list because the values of the registers used in
+ computing the CFA change during a subprogram execution. If the call frame
+ information is present, then it already encodes such changes, and it is
+ space efficient to reference that using the `DW_OP_call_frame_cfa`
+ operation.</i>
+
+5. `DW_OP_fbreg`
+
+ `DW_OP_fbreg` has a single signed LEB128 integer operand that represents a
+ byte displacement B.
+
+ The location description L for the <i>frame base</i> of the current
+ subprogram is obtained from the `DW_AT_frame_base` attribute of the debugger
+ information entry corresponding to the current subprogram as described in
+ [3.3.5 Low-Level Information](#low-level-information).
+
+ The location description L is updated by bit offset B scaled by 8 (the byte
+ size) and pushed on the stack.
+
+6. `DW_OP_breg0`, `DW_OP_breg1`, ..., `DW_OP_breg31`
+
+ The `DW_OP_breg<N>` operations encode the numbers of up to 32 registers,
+ numbered from 0 through 31, inclusive. The register number R corresponds to
+ the N in the operation name.
+
+ They have a single signed LEB128 integer operand that represents a byte
+ displacement B.
+
+ The address space identifier AS is defined as the one corresponding to the
+ target architecture specific default address space.
+
+ The address size S is defined as the address bit size of the target
+ architecture specific address space corresponding to AS.
+
+ The contents of the register specified by R are retrieved as if a
+ `DW_OP_regval_type R, DR` operation was performed where DR is the offset of
+ a hypothetical debug information entry in the current compilation unit for
+ an unsigned integral base type of size S bits. B is added and the least
+ significant S bits are treated as an unsigned value to be used as an address
+ A.
+
+ They push a location description L comprising one memory location
+ description LS on the stack. LS specifies the memory location storage that
+ corresponds to AS with a bit offset equal to A scaled by 8 (the byte size).
+
+7. `DW_OP_bregx`
+
+ `DW_OP_bregx` has two operands. The first is an unsigned LEB128 integer that
+ represents a register number R. The second is a signed LEB128 integer that
+ represents a byte displacement B.
+
+ The action is the same as for `DW_OP_breg<N>`, except that R is used as the
+ register number and B is used as the byte displacement.
+
+###### A.2.5.4.4.4 Register Location Description Operations
+
+> NOTE: This section replaces DWARF Version 5 section 2.6.1.1.3.
+
+There is a register location storage that corresponds to each of the target
+architecture registers. The size of each register location storage corresponds
+to the size of the corresponding target architecture register.
+
+A register location description specifies a register location storage. The bit
+offset corresponds to a bit position within the register. Bits accessed using a
+register location description access the corresponding target architecture
+register starting at the specified bit offset.
+
+1. `DW_OP_reg0`, `DW_OP_reg1`, ..., `DW_OP_reg31`
+
+ `DW_OP_reg<N>` operations encode the numbers of up to 32 registers, numbered
+ from 0 through 31, inclusive. The target architecture register number R
+ corresponds to the N in the operation name.
+
+ The operation is equivalent to performing `DW_OP_regx R`.
+
+2. `DW_OP_regx`
+
+ `DW_OP_regx` has a single unsigned LEB128 integer operand that represents a
+ target architecture register number R.
+
+ If the current call frame is the top call frame, it pushes a location
+ description L that specifies one register location description SL on the
+ stack. SL specifies the register location storage that corresponds to R with
+ a bit offset of 0 for the current thread.
+
+ If the current call frame is not the top call frame, call frame information
+ (see [6.4 Call Frame Information](#call-frame-information)) is used to
+ determine the location description that holds the register for the current
+ call frame and current program location of the current thread. The resulting
+ location description L is pushed.
+
+ <i>Note that if call frame information is used, the resulting location
+ description may be register, memory, or undefined.</i>
+
+ <i>An implementation may evaluate the call frame information immediately, or
+ may defer evaluation until L is accessed by an operation. If evaluation is
+ deferred, R and the current context can be recorded in L. When accessed, the
+ recorded context is used to evaluate the call frame information, not the
+ current context of the access operation.</i>
+
+<i>These operations obtain a register location. To fetch the contents of a
+register, it is necessary to use `DW_OP_regval_type`, use one of the
+`DW_OP_breg*` register-based addressing operations, or use `DW_OP_deref*` on a
+register location description.</i>
+
+###### A.2.5.4.4.5 Implicit Location Description Operations
+
+> NOTE: This section replaces DWARF Version 5 section 2.6.1.1.4.
+
+Implicit location storage represents a piece or all of an object which has no
+actual location in the program but whose contents are nonetheless known, either
+as a constant or can be computed from other locations and values in the program.
+
+An implicit location description specifies an implicit location storage. The bit
+offset corresponds to a bit position within the implicit location storage. Bits
+accessed using an implicit location description, access the corresponding
+implicit storage value starting at the bit offset.
+
+1. `DW_OP_implicit_value`
+
+ `DW_OP_implicit_value` has two operands. The first is an unsigned LEB128
+ integer that represents a byte size S. The second is a block of bytes with a
+ length equal to S treated as a literal value V.
+
+ An implicit location storage LS is created with the literal value V and a
+ size of S.
+
+ It pushes location description L with one implicit location description SL
+ on the stack. SL specifies LS with a bit offset of 0.
+
+2. `DW_OP_stack_value`
+
+ `DW_OP_stack_value` pops one stack entry that must be a value V.
+
+ An implicit location storage LS is created with the literal value V using
+ the size, encoding, and enianity specified by V's base type.
+
+ It pushes a location description L with one implicit location description SL
+ on the stack. SL specifies LS with a bit offset of 0.
+
+ <i>The `DW_OP_stack_value` operation specifies that the object does not
+ exist in memory, but its value is nonetheless known. In this form, the
+ location description specifies the actual value of the object, rather than
+ specifying the memory or register storage that holds the value.</i>
+
+ See [2.5.4.4.5 Implicit Location Description
+ Operations](#implicit-location-description-operations) for special
+ rules concerning implicit pointer values produced by dereferencing implicit
+ location descriptions created by the `DW_OP_implicit_pointer` operation.
+
+ > NOTE: Since location descriptions are allowed on the stack, the
+ > `DW_OP_stack_value` operation no longer terminates the DWARF operation
+ > expression execution as in DWARF Version 5.
+
+3. `DW_OP_implicit_pointer`
+
+ <i>An optimizing compiler may eliminate a pointer, while still retaining the
+ value that the pointer addressed. `DW_OP_implicit_pointer` allows a producer
+ to describe this value.</i>
+
+ <i>`DW_OP_implicit_pointer` specifies an object is a pointer to the target
+ architecture default address space that cannot be represented as a real
+ pointer, even though the value it would point to can be described. In this
+ form, the location description specifies a debugging information entry that
+ represents the actual location description of the object to which the
+ pointer would point. Thus, a consumer of the debug information would be able
+ to access the dereferenced pointer, even when it cannot access the pointer
+ itself.</i>
+
+ `DW_OP_implicit_pointer` has two operands. The first operand is a 4-byte
+ unsigned value in the 32-bit DWARF format, or an 8-byte unsigned value in
+ the 64-bit DWARF format, that represents the byte offset DR of a debugging
+ information entry D relative to the beginning of the `.debug_info` section
+ that contains the current compilation unit. The second operand is a signed
+ LEB128 integer that represents a byte displacement B.
+
+ <i>Note that D may not be in the current compilation unit.</i>
+
+ <i>The first operand interpretation is exactly like that for
+ `DW_FORM_ref_addr`.</i>
+
+ The address space identifier AS is defined as the one corresponding to the
+ target architecture specific default address space.
+
+ The address size S is defined as the address bit size of the target
+ architecture specific address space corresponding to AS.
+
+ An implicit location storage LS is created with the debugging information
+ entry D, address space AS, and size of S.
+
+ It pushes a location description L that comprises one implicit location
+ description SL on the stack. SL specifies LS with a bit offset of 0.
+
+ It is an evaluation error if a `DW_OP_deref*` operation pops a location
+ description L', and retrieves S bits, such that any retrieved bits come from
+ an implicit location storage that is the same as LS, unless both the
+ following conditions are met:
+
+ 1. All retrieved bits come from an implicit location description that
+ refers to an implicit location storage that is the same as LS.
+
+ <i>Note that all bits do not have to come from the same implicit
+ location description, as L' may involve composite location
+ descriptors.</i>
+
+ 2. The bits come from consecutive ascending offsets within their respective
+ implicit location storage.
+
+ <i>These rules are equivalent to retrieving the complete contents of LS.</i>
+
+ If both the above conditions are met, then the value V pushed by the
+ `DW_OP_deref*` operation is an implicit pointer value IPV with a target
+ architecture specific address space of AS, a debugging information entry of
+ D, and a base type of T. If AS is the target architecture default address
+ space, then T is the generic type. Otherwise, T is a target architecture
+ specific integral type with a bit size equal to S.
+
+ If IPV is either implicitly converted to a location description (only done
+ if AS is the target architecture default address space), then the resulting
+ location description RL is:
+
+ - If D has a `DW_AT_location` attribute, the DWARF expression E from the
+ `DW_AT_location` attribute is evaluated with the current context, except
+ that the result kind is a location description, the compilation unit is
+ the one that contains D, the object is unspecified, and the initial stack
+ is empty. RL is the expression result.
+
+ <i>Note that E is evaluated with the context of the expression accessing
+ IPV, and not the context of the expression that contained the
+ `DW_OP_implicit_pointer` operation that created L.</i>
+
+ - If D has a `DW_AT_const_value` attribute, then an implicit location
+ storage RLS is created from the `DW_AT_const_value` attribute's value with
+ a size matching the size of the `DW_AT_const_value` attribute's value. RL
+ comprises one implicit location description SRL. SRL specifies RLS with a
+ bit offset of 0.
+
+ > NOTE: If using `DW_AT_const_value` for variables and formal parameters
+ > is deprecated and instead `DW_AT_location` is used with an implicit
+ > location description, then this rule would not be required.
+
+ - Otherwise, it is an evaluation error.
+
+ The location description RL is updated by bit offset B scaled by 8 (the byte
+ size).
+
+ If a `DW_OP_stack_value` operation pops a value that is the same as IPV,
+ then it pushes a location description that is the same as L.
+
+ It is an evaluation error if LS or IPV is accessed in any other manner.
+
+ <i>The restrictions on how an implicit pointer location description created
+ by `DW_OP_implicit_pointer` can be used are to simplify the DWARF consumer.
+ Similarly, for an implicit pointer value created by `DW_OP_deref*` and
+ `DW_OP_stack_value`.</i>
+
+<i>Typically a `DW_OP_implicit_pointer` operation is used in a DWARF expression
+E<sub>1</sub> of a `DW_TAG_variable` or `DW_TAG_formal_parameter` debugging
+information entry D<sub>1</sub>'s `DW_AT_location` attribute. The debugging
+information entry referenced by the `DW_OP_implicit_pointer` operation is
+typically itself a `DW_TAG_variable` or `DW_TAG_formal_parameter` debugging
+information entry D<sub>2</sub> whose `DW_AT_location` attribute gives a second
+DWARF expression E<sub>2</sub>.</i>
+
+<i>D<sub>1</sub> and E<sub>1</sub> are describing the location of a pointer type
+object. D<sub>2</sub> and E<sub>2</sub> are describing the location of the
+object pointed to by that pointer object.</i>
+
+<i>However, D<sub>2</sub> may be any debugging information entry that contains a
+`DW_AT_location` or `DW_AT_const_value` attribute (for example,
+`DW_TAG_dwarf_procedure`). By using E<sub>2</sub>, a consumer can reconstruct
+the value of the object when asked to dereference the pointer described by
+E<sub>1</sub> which contains the `DW_OP_implicit_pointer` operation.</i>
+
+###### A.2.5.4.4.6 Composite Location Description Operations
+
+> NOTE: This section replaces DWARF Version 5 section 2.6.1.2.
+
+A composite location storage represents an object or value which may be
+contained in part of another location storage or contained in parts of more than
+one location storage.
+
+Each part has a part location description L and a part bit size S. L can have
+one or more single location descriptions SL. If there are more than one SL then
+that indicates that part is located in more than one place. The bits of each
+place of the part comprise S contiguous bits from the location storage LS
+specified by SL starting at the bit offset specified by SL. All the bits must be
+within the size of LS or the DWARF expression is ill-formed.
+
+A composite location storage can have zero or more parts. The parts are
+contiguous such that the zero-based location storage bit index will range over
+each part with no gaps between them. Therefore, the size of a composite location
+storage is the sum of the size of its parts. The DWARF expression is ill-formed
+if the size of the contiguous location storage is larger than the size of the
+memory location storage corresponding to the largest target architecture
+specific address space.
+
+A composite location description specifies a composite location storage. The bit
+offset corresponds to a bit position within the composite location storage.
+
+There are operations that create a composite location storage.
+
+There are other operations that allow a composite location storage to be
+incrementally created. Each part is created by a separate operation. There may
+be one or more operations to create the final composite location storage. A
+series of such operations describes the parts of the composite location storage
+that are in the order that the associated part operations are executed.
+
+To support incremental creation, a composite location storage can be in an
+incomplete state. When an incremental operation operates on an incomplete
+composite location storage, it adds a new part.
+
+A composite location description that specifies a composite location storage
+that is incomplete is termed an incomplete composite location description. A
+composite location description that specifies a composite location storage that
+is complete is termed a complete composite location description.
+
+If the top stack entry is a location description that has one incomplete
+composite location description SL after the execution of an operation expression
+has completed, SL is converted to a complete composite location description.
+
+<i>Note that this conversion does not happen after the completion of an
+operation expression that is evaluated on the same stack by the `DW_OP_call*`
+operations. Such executions are not a separate evaluation of an operation
+expression, but rather the continued evaluation of the same operation expression
+that contains the `DW_OP_call*` operation.</i>
+
+If a stack entry is required to be a location description L, but L has an
+incomplete composite location description, then the DWARF expression is
+ill-formed. The exception is for the operations involved in incrementally
+creating a composite location description as described below.
+
+<i>Note that a DWARF operation expression may arbitrarily compose composite
+location descriptions from any other location description, including those that
+have multiple single location descriptions, and those that have composite
+location descriptions.</i>
+
+<i>The incremental composite location description operations are defined to be
+compatible with the definitions in DWARF Version 5.</i>
+
+1. `DW_OP_piece`
+
+ `DW_OP_piece` has a single unsigned LEB128 integer that represents a byte
+ size S.
+
+ The action is based on the context:
+
+ - If the stack is empty, then a location description L comprised of one
+ incomplete composite location description SL is pushed on the stack.
+
+ An incomplete composite location storage LS is created with a single part
+ P. P specifies a location description PL and has a bit size of S scaled by
+ 8 (the byte size). PL is comprised of one undefined location description
+ PSL.
+
+ SL specifies LS with a bit offset of 0.
+
+ - Otherwise, if the top stack entry is a location description L comprised of
+ one incomplete composite location description SL, then the incomplete
+ composite location storage LS that SL specifies is updated to append a new
+ part P. P specifies a location description PL and has a bit size of S
+ scaled by 8 (the byte size). PL is comprised of one undefined location
+ description PSL. L is left on the stack.
+ - Otherwise, if the top stack entry is a location description or can be
+ converted to one, then it is popped and treated as a part location
+ description PL. Then:
+
+ - If the top stack entry (after popping PL) is a location description L
+ comprised of one incomplete composite location description SL, then the
+ incomplete composite location storage LS that SL specifies is updated to
+ append a new part P. P specifies the location description PL and has a
+ bit size of S scaled by 8 (the byte size). L is left on the stack.
+ - Otherwise, a location description L comprised of one
+ incomplete composite location description SL is pushed on
+ the stack.
+
+ An incomplete composite location storage LS is created with a single
+ part P. P specifies the location description PL and has a bit size of S
+ scaled by 8 (the byte size).
+
+ SL specifies LS with a bit offset of 0.
+
+ - Otherwise, the DWARF expression is ill-formed
+
+ <i>Many compilers store a single variable in sets of registers or store a
+ variable partially in memory and partially in registers. `DW_OP_piece`
+ provides a way of describing where a part of a variable is located.</i>
+
+ <i>The evaluation rules for the `DW_OP_piece` operation allow it to be
+ compatible with the DWARF Version 5 definition.</i>
+
+ > NOTE: Since these extensions allow location descriptions to be entries on
+ > the stack, a simpler operation to create composite location descriptions
+ > could be defined. For example, just one operation that specifies how many
+ > parts, and pops pairs of stack entries for the part size and location
+ > description. Not only would this be a simpler operation and avoid the
+ > complexities of incomplete composite location descriptions, but it may
+ > also have a smaller encoding in practice. However, the desire for
+ > compatibility with DWARF Version 5 is likely a stronger consideration.
+
+2. `DW_OP_bit_piece`
+
+ `DW_OP_bit_piece` has two operands. The first is an unsigned LEB128 integer
+ that represents the part bit size S. The second is an unsigned LEB128
+ integer that represents a bit displacement B.
+
+ The action is the same as for `DW_OP_piece`, except that any part created
+ has the bit size S, and the location description PL of any created part is
+ updated by a bit offset B.
+
+ <i>`DW_OP_bit_piece` is used instead of `DW_OP_piece` when the piece to be
+ assembled is not byte-sized or is not at the start of the part location
+ description.</i>
+
+#### A.2.5.5 DWARF Location List Expressions
+
+> NOTE: This section replaces DWARF Version 5 section 2.6.2.
+
+<i>To meet the needs of recent computer architectures and optimization
+techniques, debugging information must be able to describe the location of an
+object whose location changes over the object's lifetime, and may reside at
+multiple locations during parts of an object's lifetime. Location list
+expressions are used in place of operation expressions whenever the object whose
+location is being described has these requirements.</i>
+
+A location list expression consists of a series of location list entries. Each
+location list entry is one of the following kinds:
+
+1. <i>Bounded location description</i>
+
+ This kind of location list entry provides an operation expression that
+ evaluates to the location description of an object that is valid over a
+ lifetime bounded by a starting and ending address. The starting address is
+ the lowest address of the address range over which the location is valid.
+ The ending address is the address of the first location past the highest
+ address of the address range.
+
+ The location list entry matches when the current program location is within
+ the given range.
+
+ There are several kinds of bounded location description entries which differ
+ in the way that they specify the starting and ending addresses.
+
+2. <i>Default location description</i>
+
+ This kind of location list entry provides an operation expression that
+ evaluates to the location description of an object that is valid when no
+ bounded location description entry applies.
+
+ The location list entry matches when the current program location is not
+ within the range of any bounded location description entry.
+
+3. <i>Base address</i>
+
+ This kind of location list entry provides an address to be used as the base
+ address for beginning and ending address offsets given in certain kinds of
+ bounded location description entries. The applicable base address of a
+ bounded location description entry is the address specified by the closest
+ preceding base address entry in the same location list. If there is no
+ preceding base address entry, then the applicable base address defaults to
+ the base address of the compilation unit (see DWARF Version 5 section
+ 3.1.1).
+
+ In the case of a compilation unit where all of the machine code is contained
+ in a single contiguous section, no base address entry is needed.
+
+4. <i>End-of-list</i>
+
+ This kind of location list entry marks the end of the location list
+ expression.
+
+The address ranges defined by the bounded location description entries of a
+location list expression may overlap. When they do, they describe a situation in
+which an object exists simultaneously in more than one place.
+
+If all of the address ranges in a given location list expression do not
+collectively cover the entire range over which the object in question is
+defined, and there is no following default location description entry, it is
+assumed that the object is not available for the portion of the range that is
+not covered.
+
+The result of the evaluation of a DWARF location list expression is:
+
+- If the current program location is not specified, then it is an evaluation
+ error.
+
+ > NOTE: If the location list only has a single default entry, should that be
+ > considered a match if there is no program location? If there are non-default
+ > entries then it seems it has to be an evaluation error when there is no
+ > program location as that indicates the location depends on the program
+ > location which is not known.
+
+- If there are no matching location list entries, then the result is a location
+ description that comprises one undefined location description.
+- Otherwise, the operation expression E of each matching location list entry is
+ evaluated with the current context, except that the result kind is a location
+ description, the object is unspecified, and the initial stack is empty. The
+ location list entry result is the location description returned by the
+ evaluation of E.
+
+ The result is a location description that is comprised of the union of the
+ single location descriptions of the location description result of each
+ matching location list entry.
+
+A location list expression can only be used as the value of a debugger
+information entry attribute that is encoded using class `loclist` or
+`loclistsptr` (see [7.5.5 Classes and Forms](#classes-and-forms)). The value of
+the attribute provides an index into a separate object file section called
+`.debug_loclists` or `.debug_loclists.dwo` (for split DWARF object files) that
+contains the location list entries.
+
+A `DW_OP_call*` and `DW_OP_implicit_pointer` operation can be used to specify a
+debugger information entry attribute that has a location list expression.
+Several debugger information entry attributes allow DWARF expressions that are
+evaluated with an initial stack that includes a location description that may
+originate from the evaluation of a location list expression.
+
+<i>This location list representation, the `loclist` and `loclistsptr` class, and
+the related `DW_AT_loclists_base` attribute are new in DWARF Version 5. Together
+they eliminate most, or all of the code object relocations previously needed for
+location list expressions.</i>
+
+> NOTE: The rest of this section is the same as DWARF Version 5 section 2.6.2.
+
+## A.3 Program Scope Entries
+
+> NOTE: This section provides changes to existing debugger information entry
+> attributes. These would be incorporated into the corresponding DWARF Version 5
+> chapter 3 sections.
+
+### A.3.3 Subroutine and Entry Point Entries
+
+#### A.3.3.5 Low-Level Information
+
+1. A `DW_TAG_subprogram`, `DW_TAG_inlined_subroutine`, or `DW_TAG_entry_point`
+ debugger information entry may have a `DW_AT_return_addr` attribute, whose
+ value is a DWARF expression E.
+
+ The result of the attribute is obtained by evaluating E with a context that
+ has a result kind of a location description, an unspecified object, the
+ compilation unit that contains E, an empty initial stack, and other context
+ elements corresponding to the source language thread of execution upon which
+ the user is focused, if any. The result of the evaluation is the location
+ description L of the place where the return address for the current call
+ frame's subprogram or entry point is stored.
+
+ The DWARF is ill-formed if L is not comprised of one memory location
+ description for one of the target architecture specific address spaces.
+
+ > NOTE: It is unclear why `DW_TAG_inlined_subroutine` has a
+ > `DW_AT_return_addr` attribute but not a `DW_AT_frame_base` or
+ > `DW_AT_static_link` attribute. Seems it would either have all of them or
+ > none. Since inlined subprograms do not have a call frame it seems they
+ > would have none of these attributes.
+
+2. A `DW_TAG_subprogram` or `DW_TAG_entry_point` debugger information entry may
+ have a `DW_AT_frame_base` attribute, whose value is a DWARF expression E.
+
+ The result of the attribute is obtained by evaluating E with a context that
+ has a result kind of a location description, an unspecified object, the
+ compilation unit that contains E, an empty initial stack, and other context
+ elements corresponding to the source language thread of execution upon which
+ the user is focused, if any.
+
+ The DWARF is ill-formed if E contains an `DW_OP_fbreg` operation, or the
+ resulting location description L is not comprised of one single location
+ description SL.
+
+ If SL is a register location description for register R, then L is replaced
+ with the result of evaluating a `DW_OP_bregx R, 0` operation. This computes
+ the frame base memory location description in the target architecture
+ default address space.
+
+ <i>This allows the more compact `DW_OP_reg*` to be used instead of
+ `DW_OP_breg* 0`.</i>
+
+ > NOTE: This rule could be removed and require the producer to create the
+ > required location description directly using `DW_OP_call_frame_cfa` or
+ > `DW_OP_breg*`. This would also then allow a target to implement the call
+ > frames within a large register.
+
+ Otherwise, the DWARF is ill-formed if SL is not a memory location
+ description in any of the target architecture specific address spaces.
+
+ The resulting L is the <i>frame base</i> for the subprogram or entry point.
+
+ <i>Typically, E will use the `DW_OP_call_frame_cfa` operation or be a stack
+ pointer register plus or minus some offset.</i>
+
+3. If a `DW_TAG_subprogram` or `DW_TAG_entry_point` debugger information entry
+ is lexically nested, it may have a `DW_AT_static_link` attribute, whose
+ value is a DWARF expression E.
+
+ The result of the attribute is obtained by evaluating E with a context that
+ has a result kind of a location description, an unspecified object, the
+ compilation unit that contains E, an empty initial stack, and other context
+ elements corresponding to the source language thread of execution upon which
+ the user is focused, if any. The result of the evaluation is the location
+ description L of the <i>canonical frame address</i> (see [6.4 Call Frame
+ Information](#call-frame-information)) of the relevant call frame of the
+ subprogram instance that immediately lexically encloses the current call
+ frame's subprogram or entry point.
+
+ The DWARF is ill-formed if L is is not comprised of one memory location
+ description for one of the target architecture specific address spaces.
+
+### A.3.4 Call Site Entries and Parameters
+
+#### A.3.4.2 Call Site Parameters
+
+1. A `DW_TAG_call_site_parameter` debugger information entry may have a
+ `DW_AT_call_value` attribute, whose value is a DWARF operation expression
+ E<sub>1</sub>.
+
+ The result of the `DW_AT_call_value` attribute is obtained by evaluating
+ E<sub>1</sub> with a context that has a result kind of a value, an unspecified
+ object, the compilation unit that contains E, an empty initial stack, and other
+ context elements corresponding to the source language thread of execution upon
+ which the user is focused, if any. The resulting value V<sub>1</sub> is the
+ value of the parameter at the time of the call made by the call site.
+
+ For parameters passed by reference, where the code passes a pointer to a
+ location which contains the parameter, or for reference type parameters, the
+ `DW_TAG_call_site_parameter` debugger information entry may also have a
+ `DW_AT_call_data_location` attribute whose value is a DWARF operation expression
+ E<sub>2</sub>, and a `DW_AT_call_data_value` attribute whose value is a DWARF
+ operation expression E<sub>3</sub>.
+
+ The value of the `DW_AT_call_data_location` attribute is obtained by evaluating
+ E<sub>2</sub> with a context that has a result kind of a location description,
+ an unspecified object, the compilation unit that contains E, an empty initial
+ stack, and other context elements corresponding to the source language thread of
+ execution upon which the user is focused, if any. The resulting location
+ description L<sub>2</sub> is the location where the referenced parameter lives
+ during the call made by the call site. If E<sub>2</sub> would just be a
+ `DW_OP_push_object_address`, then the `DW_AT_call_data_location` attribute may
+ be omitted.
+
+ > NOTE: The DWARF Version 5 implies that `DW_OP_push_object_address` may be
+ > used but does not state what object must be specified in the context.
+ > Either `DW_OP_push_object_address` cannot be used, or the object to be
+ > passed in the context must be defined.
+
+ The value of the `DW_AT_call_data_value` attribute is obtained by evaluating
+ E<sub>3</sub> with a context that has a result kind of a value, an unspecified
+ object, the compilation unit that contains E, an empty initial stack, and other
+ context elements corresponding to the source language thread of execution upon
+ which the user is focused, if any. The resulting value V<sub>3</sub> is the
+ value in L<sub>2</sub> at the time of the call made by the call site.
+
+ The result of these attributes is undefined if the current call frame is not for
+ the subprogram containing the `DW_TAG_call_site_parameter` debugger information
+ entry or the current program location is not for the call site containing the
+ `DW_TAG_call_site_parameter` debugger information entry in the current call
+ frame.
+
+ <i>The consumer may have to virtually unwind to the call site (see [6.4 Call
+ Frame Information](#call-frame-information)) in order to evaluate these
+ attributes. This will ensure the source language thread of execution upon which
+ the user is focused corresponds to the call site needed to evaluate the
+ expression.</i>
+
+ If it is not possible to avoid the expressions of these attributes from
+ accessing registers or memory locations that might be clobbered by the
+ subprogram being called by the call site, then the associated attribute should
+ not be provided.
+
+ <i>The reason for the restriction is that the parameter may need to be accessed
+ during the execution of the callee. The consumer may virtually unwind from the
+ called subprogram back to the caller and then evaluate the attribute
+ expressions. The call frame information (see [6.4 Call Frame
+ Information](#call-frame-information)) will not be able to restore registers
+ that have been clobbered, and clobbered memory will no longer have the value at
+ the time of the call.</i>
+
+### A.3.5 Lexical Block Entries
+
+> NOTE: This section is the same as DWARF Version 5 section 3.5.
+
+## A.4 Data Object and Object List Entries
+
+> NOTE: This section provides changes to existing debugger information entry
+> attributes. These would be incorporated into the corresponding DWARF Version 5
+> chapter 4 sections.
+
+### A.4.1 Data Object Entries
+
+1. Any debugging information entry describing a data object (which includes
+ variables and parameters) or common blocks may have a `DW_AT_location`
+ attribute, whose value is a DWARF expression E.
+
+ The result of the attribute is obtained by evaluating E with a context that
+ has a result kind of a location description, an unspecified object, the
+ compilation unit that contains E, an empty initial stack, and other context
+ elements corresponding to the source language thread of execution upon which
+ the user is focused, if any. The result of the evaluation is the location
+ description of the base of the data object.
+
+ See [2.5.4.2 Control Flow Operations](#control-flow-operations) for special
+ evaluation rules used by the `DW_OP_call*` operations.
+
+ > NOTE: Delete the description of how the `DW_OP_call*` operations evaluate
+ > a `DW_AT_location` attribute as that is now described in the operations.
+
+ > NOTE: See the discussion about the `DW_AT_location` attribute in the
+ > `DW_OP_call*` operation. Having each attribute only have a single purpose
+ > and single execution semantics seems desirable. It makes it easier for the
+ > consumer that no longer have to track the context. It makes it easier for
+ > the producer as it can rely on a single semantics for each attribute.
+ >
+ > For that reason, limiting the `DW_AT_location` attribute to only
+ > supporting evaluating the location description of an object, and using a
+ > different attribute and encoding class for the evaluation of DWARF
+ > expression <i>procedures</i> on the same operation expression stack seems
+ > desirable.
+
+2. `DW_AT_const_value`
+
+ > NOTE: Could deprecate using the `DW_AT_const_value` attribute for
+ > `DW_TAG_variable` or `DW_TAG_formal_parameter` debugger information
+ > entries that have been optimized to a constant. Instead, `DW_AT_location`
+ > could be used with a DWARF expression that produces an implicit location
+ > description now that any location description can be used within a DWARF
+ > expression. This allows the `DW_OP_call*` operations to be used to push
+ > the location description of any variable regardless of how it is
+ > optimized.
+
+## A.5 Type Entries
+
+> NOTE: This section provides changes to existing debugger information entry
+> attributes. These would be incorporated into the corresponding DWARF Version 5
+> chapter 5 sections.
+
+### A.5.7 Structure, Union, Class and Interface Type Entries
+
+#### A.5.7.3 Derived or Extended Structures, Classes and Interfaces
+
+1. For a `DW_AT_data_member_location` attribute there are two cases:
+
+ 1. If the attribute is an integer constant B, it provides the offset in
+ bytes from the beginning of the containing entity.
+
+ The result of the attribute is obtained by updating the bit offset of
+ the location description of the beginning of the containing entity by B
+ scaled by 8 (the byte size). The result is the location description of
+ the base of the member entry.
+
+ <i>If the beginning of the containing entity is not byte aligned, then
+ the beginning of the member entry has the same bit displacement within a
+ byte.</i>
+
+ 2. Otherwise, the attribute must be a DWARF expression E which is evaluated
+ with a context that has a result kind of a location description, an
+ unspecified object, the compilation unit that contains E, an initial
+ stack comprising the location description of the beginning of the
+ containing entity, and other context elements corresponding to the
+ source language thread of execution upon which the user is focused, if
+ any. The result of the evaluation is the location description of the
+ base of the member entry.
+
+ > NOTE: The beginning of the containing entity can now be any location
+ > description, including those with more than one single location
+ > description, and those with single location descriptions that are of any
+ > kind and have any bit offset.
+
+#### A.5.7.8 Member Function Entries
+
+1. An entry for a virtual function also has a `DW_AT_vtable_elem_location`
+ attribute whose value is a DWARF expression E.
+
+ The result of the attribute is obtained by evaluating E with a context that
+ has a result kind of a location description, an unspecified object, the
+ compilation unit that contains E, an initial stack comprising the location
+ description of the object of the enclosing type, and other context elements
+ corresponding to the source language thread of execution upon which the user
+ is focused, if any. The result of the evaluation is the location description
+ of the slot for the function within the virtual function table for the
+ enclosing class.
+
+### A.5.14 Pointer to Member Type Entries
+
+1. The `DW_TAG_ptr_to_member_type` debugging information entry has a
+ `DW_AT_use_location` attribute whose value is a DWARF expression E. It is used
+ to compute the location description of the member of the class to which the
+ pointer to member entry points.
+
+ <i>The method used to find the location description of a given member of a
+ class, structure, or union is common to any instance of that class, structure,
+ or union and to any instance of the pointer to member type. The method is thus
+ associated with the pointer to member type, rather than with each object that
+ has a pointer to member type.</i>
+
+ The `DW_AT_use_location` DWARF expression is used in conjunction with the
+ location description for a particular object of the given pointer to member type
+ and for a particular structure or class instance.
+
+ The result of the attribute is obtained by evaluating E with a context that has
+ a result kind of a location description, an unspecified object, the compilation
+ unit that contains E, an initial stack comprising two entries, and other context
+ elements corresponding to the source language thread of execution upon which the
+ user is focused, if any. The first stack entry is the value of the pointer to
+ member object itself. The second stack entry is the location description of the
+ base of the entire class, structure, or union instance containing the member
+ whose location is being calculated. The result of the evaluation is the location
+ description of the member of the class to which the pointer to member entry
+ points.
+
+### A.5.16 Dynamic Type Entries
+
+1. The `DW_AT_data_location` attribute may be used with any type that provides one
+ or more levels of hidden indirection and/or run-time parameters in its
+ representation. Its value is a DWARF operation expression E which computes the
+ location description of the data for an object. When this attribute is omitted,
+ the location description of the data is the same as the location description of
+ the object.
+
+ The result of the attribute is obtained by evaluating E with a context that has
+ a result kind of a location description, an object that is the location
+ description of the data descriptor, the compilation unit that contains E, an
+ empty initial stack, and other context elements corresponding to the source
+ language thread of execution upon which the user is focused, if any. The result
+ of the evaluation is the location description of the base of the member entry.
+
+ <i>E will typically involve an operation expression that begins with a
+ `DW_OP_push_object_address` operation which loads the location description
+ of the object which can then serve as a descriptor in subsequent
+ calculation.</i>
+
+ > NOTE: Since `DW_AT_data_member_location`, `DW_AT_use_location`, and
+ > `DW_AT_vtable_elem_location` allow both operation expressions and location
+ > list expressions, why does `DW_AT_data_location` not allow both? In all cases
+ > they apply to data objects so less likely that optimization would cause
+ > different operation expressions for different program location ranges. But if
+ > supporting for some then should be for all.
+ >
+ > It seems odd this attribute is not the same as `DW_AT_data_member_location` in
+ > having an initial stack with the location description of the object since the
+ > expression has to need it.
+
+## A.6 Other Debugging Information
+
+> NOTE: This section provides changes to existing debugger information entry
+> attributes. These would be incorporated into the corresponding DWARF Version 5
+> chapter 6 sections.
+
+### A.6.2 Line Number Information
+
+> NOTE: This section is the same as DWARF Version 5 section 6.2.
+
+### A.6.4 Call Frame Information
+
+> NOTE: This section provides changes to DWARF Version 5 section 6.4. Register
+> unwind DWARF expressions are generalized to allow any location description,
+> including those with composite and implicit location descriptions.
+
+#### A.6.4.1 Structure of Call Frame Information
+
+The register rules are:
+
+1. <i>undefined</i>
+
+ A register that has this rule has no recoverable value in the previous
+ frame. The previous value of this register is the undefined location
+ description (see [2.5.4.4.2 Undefined Location Description
+ Operations](#undefined-location-description-operations)).
+
+ <i>By convention, the register is not preserved by a callee.</i>
+
+2. <i>same value</i>
+
+ This register has not been modified from the previous caller frame.
+
+ If the current frame is the top frame, then the previous value of this
+ register is the location description L that specifies one register location
+ description SL. SL specifies the register location storage that corresponds
+ to the register with a bit offset of 0 for the current thread.
+
+ If the current frame is not the top frame, then the previous value of this
+ register is the location description obtained using the call frame
+ information for the callee frame and callee program location invoked by the
+ current caller frame for the same register.
+
+ <i>By convention, the register is preserved by the callee, but the callee
+ has not modified it.</i>
+
+3. <i>offset(N)</i>
+
+ N is a signed byte offset. The previous value of this register is saved at
+ the location description L. Where L is the location description of the
+ current CFA (see [2.5.4 DWARF Operation
+ Expressions](#dwarf-operation-expressions)) updated with the bit offset N
+ scaled by 8 (the byte size).
+
+4. <i>val_offset(N)</i>
+
+ N is a signed byte offset. The previous value of this register is the memory
+ byte address of the location description L. Where L is the location
+ description of the current CFA (see [2.5.4 DWARF Operation
+ Expressions](#dwarf-operation-expressions)) updated with the bit offset N
+ scaled by 8 (the byte size).
+
+ The DWARF is ill-formed if the CFA location description is not a memory byte
+ address location description, or if the register size does not match the
+ size of an address in the target architecture default address space.
+
+ <i>Since the CFA location description is required to be a memory byte
+ address location description, the value of val_offset(N) will also be a
+ memory byte address location description since it is offsetting the CFA
+ location description by N bytes. Furthermore, the value of val_offset(N)
+ will be a memory byte address in the target architecture default address
+ space.</i>
+
+ > NOTE: Should DWARF allow the address size to be a different size to the
+ > size of the register? Requiring them to be the same bit size avoids any
+ > issue of conversion as the bit contents of the register is simply
+ > interpreted as a value of the address.
+ >
+ > GDB has a per register hook that allows a target specific conversion on a
+ > register by register basis. It defaults to truncation of bigger registers,
+ > and to actually reading bytes from the next register (or reads out of
+ > bounds for the last register) for smaller registers. There are no GDB
+ > tests that read a register out of bounds (except an illegal hand written
+ > assembly test).
+
+5. <i>register(R)</i>
+
+ This register has been stored in another register numbered R.
+
+ The previous value of this register is the location description obtained
+ using the call frame information for the current frame and current program
+ location for register R.
+
+ The DWARF is ill-formed if the size of this register does not match the size
+ of register R or if there is a cyclic dependency in the call frame
+ information.
+
+ > NOTE: Should this also allow R to be larger than this register? If so is
+ > the value stored in the low order bits and it is undefined what is stored
+ > in the extra upper bits?
+
+6. <i>expression(E)</i>
+
+ The previous value of this register is located at the location description
+ produced by evaluating the DWARF operation expression E (see [2.5.4 DWARF
+ Operation Expressions](#dwarf-operation-expressions)).
+
+ E is evaluated with the current context, except the result kind is a
+ location description, the compilation unit is unspecified, the object is
+ unspecified, and an initial stack comprising the location description of the
+ current CFA (see [2.5.4 DWARF Operation
+ Expressions](#dwarf-operation-expressions)).
+
+7. <i>val_expression(E)</i>
+
+ The previous value of this register is the value produced by evaluating the
+ DWARF operation expression E (see [2.5.4 DWARF Operation
+ Expressions](#dwarf-operation-expressions)).
+
+ E is evaluated with the current context, except the result kind is a value,
+ the compilation unit is unspecified, the object is unspecified, and an
+ initial stack comprising the location description of the current CFA (see
+ [2.5.4 DWARF Operation Expressions](#dwarf-operation-expressions)).
+
+ The DWARF is ill-formed if the resulting value type size does not match the
+ register size.
+
+ > NOTE: This has limited usefulness as the DWARF expression E can only
+ > produce values up to the size of the generic type. This is due to not
+ > allowing any operations that specify a type in a CFI operation expression.
+ > This makes it unusable for registers that are larger than the generic
+ > type. However, <i>expression(E)</i> can be used to create an implicit
+ > location description of any size.
+
+8. <i>architectural</i>
+
+ The rule is defined externally to this specification by the augmenter.
+
+A Common Information Entry (CIE) holds information that is shared among many
+Frame Description Entries (FDE). There is at least one CIE in every non-empty
+`.debug_frame` section. A CIE contains the following fields, in order:
+
+1. `length` (initial length)
+
+ A constant that gives the number of bytes of the CIE structure, not
+ including the length field itself. The size of the length field plus the
+ value of length must be an integral multiple of the address size specified
+ in the `address_size` field.
+
+2. `CIE_id` (4 or 8 bytes, see [7.4 32-Bit and 64-Bit DWARF
+ Formats](#32-bit-and-64-bit-dwarf-formats))
+
+ A constant that is used to distinguish CIEs from FDEs.
+
+ In the 32-bit DWARF format, the value of the CIE id in the CIE header is
+ 0xffffffff; in the 64-bit DWARF format, the value is 0xffffffffffffffff.
+
+3. `version` (ubyte)
+
+ A version number. This number is specific to the call frame information and
+ is independent of the DWARF version number.
+
+ The value of the CIE version number is 4.
+
+ > NOTE: Would this be increased to 5 to reflect the changes in these
+ > extensions?
+
+4. `augmentation` (sequence of UTF-8 characters)
+
+ A null-terminated UTF-8 string that identifies the augmentation to this CIE
+ or to the FDEs that use it. If a reader encounters an augmentation string
+ that is unexpected, then only the following fields can be read:
+
+ - CIE: length, CIE_id, version, augmentation
+ - FDE: length, CIE_pointer, initial_location, address_range
+
+ If there is no augmentation, this value is a zero byte.
+
+ <i>The augmentation string allows users to indicate that there is additional
+ vendor and target architecture specific information in the CIE or FDE which
+ is needed to virtually unwind a stack frame. For example, this might be
+ information about dynamically allocated data which needs to be freed on exit
+ from the routine.</i>
+
+ <i>Because the `.debug_frame` section is useful independently of any
+ `.debug_info` section, the augmentation string always uses UTF-8
+ encoding.</i>
+
+5. `address_size` (ubyte)
+
+ The size of a target address in this CIE and any FDEs that use it, in bytes.
+ If a compilation unit exists for this frame, its address size must match the
+ address size here.
+
+6. `segment_selector_size` (ubyte)
+
+ The size of a segment selector in this CIE and any FDEs that use it, in
+ bytes.
+
+7. `code_alignment_factor` (unsigned LEB128)
+
+ A constant that is factored out of all advance location instructions (see
+ [6.4.2.1 Row Creation Instructions](#row-creation-instructions)). The
+ resulting value is `(operand * code_alignment_factor)`.
+
+8. `data_alignment_factor` (signed LEB128)
+
+ A constant that is factored out of certain offset instructions (see [6.4.2.2
+ CFA Definition Instructions](#cfa-definition-instructions) and [6.4.2.3
+ Register Rule Instructions](#register-rule-instructions)). The
+ resulting value is `(operand * data_alignment_factor)`.
+
+9. `return_address_register` (unsigned LEB128)
+
+ An unsigned LEB128 constant that indicates which column in the rule table
+ represents the return address of the subprogram. Note that this column might
+ not correspond to an actual machine register.
+
+ The value of the return address register is used to determine the program
+ location of the caller frame. The program location of the top frame is the
+ target architecture program counter value of the current thread.
+
+10. `initial_instructions` (array of ubyte)
+
+ A sequence of rules that are interpreted to create the initial setting of
+ each column in the table.
+
+ The default rule for all columns before interpretation of the initial
+ instructions is the undefined rule. However, an ABI authoring body or a
+ compilation system authoring body may specify an alternate default value for
+ any or all columns.
+
+11. `padding` (array of ubyte)
+
+ Enough `DW_CFA_nop` instructions to make the size of this entry match the
+ length value above.
+
+An FDE contains the following fields, in order:
+
+1. `length` (initial length)
+
+ A constant that gives the number of bytes of the header and instruction
+ stream for this subprogram, not including the length field itself. The size
+ of the length field plus the value of length must be an integral multiple of
+ the address size.
+
+2. `CIE_pointer` (4 or 8 bytes, see [7.4 32-Bit and 64-Bit DWARF
+ Formats](#32-bit-and-64-bit-dwarf-formats))
+
+ A constant offset into the `.debug_frame` section that denotes the CIE that
+ is associated with this FDE.
+
+3. `initial_location` (segment selector and target address)
+
+ The address of the first location associated with this table entry. If the
+ segment_selector_size field of this FDE's CIE is non-zero, the initial
+ location is preceded by a segment selector of the given length.
+
+4. `address_range` (target address)
+
+ The number of bytes of program instructions described by this entry.
+
+5. `instructions` (array of ubyte)
+
+ A sequence of table defining instructions that are described in [6.4.2 Call
+ Frame Instructions](#call-frame-instructions).
+
+6. `padding` (array of ubyte)
+
+ Enough `DW_CFA_nop` instructions to make the size of this entry match the
+ length value above.
+
+#### A.6.4.2 Call Frame Instructions
+
+Some call frame instructions have operands that are encoded as DWARF operation
+expressions E (see [2.5.4 DWARF Operation
+Expressions](#dwarf-operation-expressions)). The DWARF operations that can be
+used in E have the following restrictions:
+
+- `DW_OP_addrx`, `DW_OP_call2`, `DW_OP_call4`, `DW_OP_call_ref`,
+ `DW_OP_const_type`, `DW_OP_constx`, `DW_OP_convert`, `DW_OP_deref_type`,
+ `DW_OP_fbreg`, `DW_OP_implicit_pointer`, `DW_OP_regval_type`,
+ `DW_OP_reinterpret`, and `DW_OP_xderef_type` operations are not allowed
+ because the call frame information must not depend on other debug sections.
+- `DW_OP_push_object_address` is not allowed because there is no object context
+ to provide a value to push.
+- `DW_OP_call_frame_cfa` and `DW_OP_entry_value` are not allowed because their
+ use would be circular.
+
+<i>Call frame instructions to which these restrictions apply include
+`DW_CFA_def_cfa_expression`, `DW_CFA_expression`, and
+`DW_CFA_val_expression`.</i>
+
+##### A.6.4.2.1 Row Creation Instructions
+
+> NOTE: These instructions are the same as in DWARF Version 5 section 6.4.2.1.
+
+##### A.6.4.2.2 CFA Definition Instructions
+
+1. `DW_CFA_def_cfa`
+
+ The `DW_CFA_def_cfa` instruction takes two unsigned LEB128 operands
+ representing a register number R and a (non-factored) byte displacement B.
+ The required action is to define the current CFA rule to be the result of
+ evaluating the DWARF operation expression `DW_OP_bregx R, B` as a location
+ description.
+
+2. `DW_CFA_def_cfa_sf`
+
+ The `DW_CFA_def_cfa_sf` instruction takes two operands: an unsigned LEB128
+ value representing a register number R and a signed LEB128 factored byte
+ displacement B. The required action is to define the current CFA rule to be
+ the result of evaluating the DWARF operation expression `DW_OP_bregx R, B *
+ data_alignment_factor` as a location description.
+
+ <i>The action is the same as `DW_CFA_def_cfa`, except that the second
+ operand is signed and factored.</i>
+
+3. `DW_CFA_def_cfa_register`
+
+ The `DW_CFA_def_cfa_register` instruction takes a single unsigned LEB128
+ operand representing a register number R. The required action is to define
+ the current CFA rule to be the result of evaluating the DWARF operation
+ expression `DW_OP_bregx R, B` as a location description. B is the old CFA
+ byte displacement.
+
+ If the subprogram has no current CFA rule, or the rule was defined by a
+ `DW_CFA_def_cfa_expression` instruction, then the DWARF is ill-formed.
+
+4. `DW_CFA_def_cfa_offset`
+
+ The `DW_CFA_def_cfa_offset` instruction takes a single unsigned LEB128
+ operand representing a (non-factored) byte displacement B. The required
+ action is to define the current CFA rule to be the result of evaluating the
+ DWARF operation expression `DW_OP_bregx R, B` as a location description. R
+ is the old CFA register number.
+
+ If the subprogram has no current CFA rule, or the rule was defined by a
+ `DW_CFA_def_cfa_expression` instruction, then the DWARF is ill-formed.
+
+5. `DW_CFA_def_cfa_offset_sf`
+
+ The `DW_CFA_def_cfa_offset_sf` instruction takes a signed LEB128 operand
+ representing a factored byte displacement B. The required action is to
+ define the current CFA rule to be the result of evaluating the DWARF
+ operation expression `DW_OP_bregx R, B * data_alignment_factor` as a
+ location description. R is the old CFA register number.
+
+ If the subprogram has no current CFA rule, or the rule was defined by a
+ `DW_CFA_def_cfa_expression` instruction, then the DWARF is ill-formed.
+
+ <i>The action is the same as `DW_CFA_def_cfa_offset`, except that the
+ operand is signed and factored.</i>
+
+6. `DW_CFA_def_cfa_expression`
+
+ The `DW_CFA_def_cfa_expression` instruction takes a single operand encoded
+ as a `DW_FORM_exprloc` value representing a DWARF operation expression E.
+ The required action is to define the current CFA rule to be the result of
+ evaluating E with the current context, except the result kind is a location
+ description, the compilation unit is unspecified, the object is unspecified,
+ and an empty initial stack.
+
+ <i>See [6.4.2 Call Frame Instructions](#call-frame-instructions) regarding
+ restrictions on the DWARF expression operations that can be used in E.</i>
+
+ The DWARF is ill-formed if the result of evaluating E is not a memory byte
+ address location description.
+
+##### A.6.4.2.3 Register Rule Instructions
+
+1. `DW_CFA_undefined`
+
+ The `DW_CFA_undefined` instruction takes a single unsigned LEB128 operand
+ that represents a register number R. The required action is to set the rule
+ for the register specified by R to `undefined`.
+
+2. `DW_CFA_same_value`
+
+ The `DW_CFA_same_value` instruction takes a single unsigned LEB128 operand
+ that represents a register number R. The required action is to set the rule
+ for the register specified by R to `same value`.
+
+3. `DW_CFA_offset`
+
+ The `DW_CFA_offset` instruction takes two operands: a register number R
+ (encoded with the opcode) and an unsigned LEB128 constant representing a
+ factored displacement B. The required action is to change the rule for the
+ register specified by R to be an <i>offset(B * data_alignment_factor)</i>
+ rule.
+
+ > NOTE: Seems this should be named `DW_CFA_offset_uf` since the offset is
+ > unsigned factored.
+
+4. `DW_CFA_offset_extended`
+
+ The `DW_CFA_offset_extended` instruction takes two unsigned LEB128 operands
+ representing a register number R and a factored displacement B. This
+ instruction is identical to `DW_CFA_offset`, except for the encoding and
+ size of the register operand.
+
+ > NOTE: Seems this should be named `DW_CFA_offset_extended_uf` since the
+ > displacement is unsigned factored.
+
+5. `DW_CFA_offset_extended_sf`
+
+ The `DW_CFA_offset_extended_sf` instruction takes two operands: an unsigned
+ LEB128 value representing a register number R and a signed LEB128 factored
+ displacement B. This instruction is identical to `DW_CFA_offset_extended`,
+ except that B is signed.
+
+6. `DW_CFA_val_offset`
+
+ The `DW_CFA_val_offset` instruction takes two unsigned LEB128 operands
+ representing a register number R and a factored displacement B. The required
+ action is to change the rule for the register indicated by R to be a
+ <i>val_offset(B * data_alignment_factor)</i> rule.
+
+ > NOTE: Seems this should be named `DW_CFA_val_offset_uf` since the
+ displacement is unsigned factored.
+
+7. `DW_CFA_val_offset_sf`
+
+ The `DW_CFA_val_offset_sf` instruction takes two operands: an unsigned
+ LEB128 value representing a register number R and a signed LEB128 factored
+ displacement B. This instruction is identical to `DW_CFA_val_offset`, except
+ that B is signed.
+
+8. `DW_CFA_register`
+
+ The `DW_CFA_register` instruction takes two unsigned LEB128 operands
+ representing register numbers R1 and R2 respectively. The required action is
+ to set the rule for the register specified by R1 to be a <i>register(R2)</i>
+ rule.
+
+9. `DW_CFA_expression`
+
+ The `DW_CFA_expression` instruction takes two operands: an unsigned LEB128
+ value representing a register number R, and a `DW_FORM_block` value
+ representing a DWARF operation expression E. The required action is to
+ change the rule for the register specified by R to be an
+ <i>expression(E)</i> rule.
+
+ <i>That is, E computes the location description where the register value can
+ be retrieved.</i>
+
+ <i>See [6.4.2 Call Frame Instructions](#call-frame-instructions) regarding
+ restrictions on the DWARF expression operations that can be used in E.</i>
+
+10. `DW_CFA_val_expression`
+
+ The `DW_CFA_val_expression` instruction takes two operands: an unsigned
+ LEB128 value representing a register number R, and a `DW_FORM_block` value
+ representing a DWARF operation expression E. The required action is to
+ change the rule for the register specified by R to be a
+ <i>val_expression(E)</i> rule.
+
+ <i>That is, E computes the value of register R.</i>
+
+ <i>See [6.4.2 Call Frame Instructions](#call-frame-instructions) regarding
+ restrictions on the DWARF expression operations that can be used in E.</i>
+
+ If the result of evaluating E is not a value with a base type size that
+ matches the register size, then the DWARF is ill-formed.
+
+11. `DW_CFA_restore`
+
+ The `DW_CFA_restore` instruction takes a single operand (encoded with the
+ opcode) that represents a register number R. The required action is to
+ change the rule for the register specified by R to the rule assigned it by
+ the `initial_instructions` in the CIE.
+
+12. `DW_CFA_restore_extended`
+
+ The `DW_CFA_restore_extended` instruction takes a single unsigned LEB128
+ operand that represents a register number R. This instruction is identical
+ to `DW_CFA_restore`, except for the encoding and size of the register
+ operand.
+
+##### A.6.4.2.4 Row State Instructions
+
+> NOTE: These instructions are the same as in DWARF Version 5 section 6.4.2.4.
+
+##### A.6.4.2.5 Padding Instruction
+
+> NOTE: These instructions are the same as in DWARF Version 5 section 6.4.2.5.
+
+#### A.6.4.3 Call Frame Instruction Usage
+
+> NOTE: The same as in DWARF Version 5 section 6.4.3.
+
+#### A.6.4.4 Call Frame Calling Address
+
+> NOTE: The same as in DWARF Version 5 section 6.4.4.
+
+## A.7 Data Representation
+
+> NOTE: This section provides changes to existing debugger information entry
+> attributes. These would be incorporated into the corresponding DWARF Version 5
+> chapter 7 sections.
+
+### A.7.4 32-Bit and 64-Bit DWARF Formats
+
+> NOTE: This augments DWARF Version 5 section 7.4 list item 3's table.
+
+ Form Role
+ ------------------------ --------------------------------------
+ DW_OP_implicit_pointer offset in `.debug_info`
+
+### A.7.5 Format of Debugging Information
+
+#### A.7.5.5 Classes and Forms
+
+> NOTE: The same as in DWARF Version 5 section 7.5.5.
+
+### A.7.7 DWARF Expressions
+
+> NOTE: Rename DWARF Version 5 section 7.7 to reflect the unification of
+> location descriptions into DWARF expressions.
+
+#### A.7.7.1 Operation Expressions
+
+> NOTE: Rename DWARF Version 5 section 7.7.1 and delete section 7.7.2 to reflect
+> the unification of location descriptions into DWARF expressions.
+
+#### A.7.7.3 Location List Expressions
+
+> NOTE: Rename DWARF Version 5 section 7.7.3 to reflect that location lists are
+> a kind of DWARF expression.
+
+# B. Further Information
+
+The following references provide additional information on the extension.
+
+A reference to the DWARF standard is provided.
+
+A formatted version of this extension is available on the LLVM site. It includes
+many figures that help illustrate the textual description, especially of the
+example DWARF expression evaluations.
+
+Slides and a video of a presentation at the Linux Plumbers Conference 2021
+related to this extension are available.
+
+The LLVM compiler extension includes the operations mentioned in the motivating
+examples. It also covers other extensions needed for heterogeneous devices.
+
+- [DWARF Debugging Information Format](https://dwarfstd.org/)
+ - [DWARF Debugging Information Format Version 5](https://dwarfstd.org/Dwarf5Std.php)
+- [Allow Location Descriptions on the DWARF Expression Stack](https://llvm.org/docs/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack.html)
+- DWARF extensions for optimized SIMT/SIMD (GPU) debugging - Linux Plumbers Conference 2021
+ - [Video](https://www.youtube.com/watch?v=QiR0ra0ymEY&t=10015s)
+ - [Slides](https://linuxplumbersconf.org/event/11/contributions/1012/attachments/798/1505/DWARF_Extensions_for_Optimized_SIMT-SIMD_GPU_Debugging-LPC2021.pdf)
+- [DWARF Extensions For Heterogeneous Debugging](https://llvm.org/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.html)
projects / platform / upstream / llvm.git / commitdiff