Chapter 2: General Description

2.5 DWARF Expressions [Now Chapter 3]

2.6 Location Descriptions [Now Chapter 3]

2.5 Values and Locations [NEW]

As described in Section 2.2, DWARF attributes may havedifferent classes of values. In many cases, attribute valuesdirectly provide the numeric value of a property such asbounds of an array, the size of a type, the value of anamed constant in the program, or a string value such asthe name of a variable or type.In other cases, they provide the location of a dataobject, such as the address of a variable or common block(see Section 4.1), instead of directly providing the valueof the object.

The attribute value classes constant and string are usedto provide static values for properties, but often thevalues need to be computed dynamically. The classesexprval and vallist indicate that the attribute value isto be computed by evaluating a DWARF expression (describedin Chapter 3).

A DWARF expression of class exprval can be used to computea value that cannot be given statically, such as the upperbound of a dynamic array.

Sometimes, an attribute value may depend on the programcounter, such as the loop vectorization factor. A value list(see Section 3.18), encoded using class vallist, can beused in this case. A value list is a list of DWARFexpressions, each associated with a range of programcounters.

The class address is used to provide a staticmemory address for an object located in memory, and theclasses exprloc and loclist indicate that the locationof an object is to be computed by evaluating a DWARFexpression. In these cases, where the DWARF expression isexpected to produce a location, the expression is called a“location expression.”

(In DWARF 5, the term “location description” was used torefer both to a sequence of DWARF operations that evaluatesto a location, and to the result of that evaluation. ForDWARF 6, we use the terms “location expression” for theexpression and “location” for the result ofevaluating the expression.)

The class exprloc is used to provide a locationexpression that yields a single location. This issufficient to describe the location of an object whoselifetime is either static or the same as the lexical blockthat owns it (excluding any prologue or epilogue ranges),and that does not move during its lifetime.

A location list (see Section 3.19), encoded using classloclist, describes objects that have a limited lifetimeor that change their location during their lifetime. Alocation list is a list of location expressions, eachassociated with a range of program counters.

A location list may have overlapping PC ranges, and thus mayyield multiple locations at a given PC.In this case, the consumer may assume that the object valuestored is the same in all locations, excluding bits of theobject that serve as padding. Non-padding bits that areundefined (for example, as a result of optimization) must beundefined in all the locations.

A location list that yields multiple locations can beused to describe objects that reside in more than onepiece of storage at the same time. An object may have morethan one location as a result of optimization. Forexample, a value that is only read may be promoted frommemory to a register for some region of code, but latercode may revert to reading the value from memory as theregister may be used for other purposes.

DWARF can describe the location of program objects inseveral kinds of storage, such as a memory address space ora register. Each kind of storage is treated as a linearstream of bits of finite size, organized into bytes and/orwords. The ordering of bits uses the bit numbering anddirection conventions that are appropriate to the targetarchitecture and the ABI.For example, on a little-endian architecture, bits arenumbered within bytes and words from least-significantto most-significant (right-to-left), while on a big-endianarchitecture, bits are numbered left-to-right.

A location names a block of storage and a(non-negative, zero-based) bit offset relative to the startof that storage. It gives the location of the programobject, which occupies a sequence of contiguous bitsstarting at that location. The bit offset of a location mustbe less than the size of the named block of storage (for azero-length block of storage, the offset must be 0).

DWARF can describe locations in six kinds of storage:

• Memory.Corresponds to the target architecture memory addressspaces. There is always a default address space, and thetarget architecture may define additional addressspaces.Each memory storage block is the size of the correspondingaddress space.(The offset can be thought of as a byte or word addresscombined with a bit offset within the byte or word.)

• Registers.Corresponds to the target architecture registers.Each register storage block is the size of the correspondingregister.

• Undefined storage.Indicates no value is available, as when a variable hasbeen optimized out. The location names a block ofimaginary storage that cannot be read.Writing to undefined storage has no effect.The size of an undefined storage block is the same asthat of the largest memory address space or register.

• Implicit storage.Corresponds to fixed values that can only be read, as whena variable has been optimized out but can nevertheless berematerialized from program context. The locationnames a block of imaginary storage, whose size isthe same as the fixed value that it holds.

• Implicit pointer storage.A special form of implicit storage, created by theDW_OP_implicit_pointer operator (see Section 3.11).The location names a block of imaginary storage thatholds a secondary location. Its size is the size of thepointer that was optimized away, but nophysical pointer is available.

• Composite storage.A hybrid form of storage where different pieces of aprogram object map to different locations, as when afield of a structure or a slice of an array is promotedto a register while the rest remains in memory.Composite storage consists of a (possibly empty) seriesof contiguous pieces, and its size is the sum of thesizes of the pieces. The maximum size of a block ofcomposite storage is the size of the largest addressspace or register.

…

Chapter 3: DWARF Expressions

DWARF expressions describe how to compute a value orspecify a location. They are expressed interms of DWARF operations that operate on a stack of valueselements, each of which may beeither a value or a location.

A DWARF expression is encoded as a stream of operations,each consisting of an opcode followed by zero or more literaloperands. The number of operands is implied by the opcode.

In addition to thegeneral operations that are defined here, operations that arespecific to location descriptions are defined inSection {locationdescriptions}.

The result of a DWARF expression is the value or location on the topof the stack after evaluating the operations.

Values on the stack are typed, and canrepresent a value of any supported base type of the targetmachine, or of the generic type, which is an integral typethat has the size of an address in the default address spaceon the target machine, and unspecified signedness.

The generic type is the same as the unspecified type used for stackoperations defined in DWARF Version 4 and before.

An implicit conversion between a location and a valuemay happen during the execution of any operation or whenevaluation of the expression is completed. If a location isexpected, but the result is a value of integral type, thevalue is implicitly treated as a memory address in thedefault address space, and converted to a memory location.If a value is expected, and the result is an addressablememory location (i.e., if the offset is a multiple of thebyte or word size) in the default address space, the addressis implicitly converted to a value of the generictype.

Debugging information must provide consumers a way tofind the location of program variables, determine the bounds of dynamicarrays and strings, and possibly to find the base address of asubroutine’s stack frame or the return address of a subroutine.Furthermore, to meet the needs of recent computer architectures andoptimization techniques, debugging information must be able to describethe location of an object whose location changes over the object’slifetime.

2.5.1 3.1 DWARF Expression Evaluation Context

DWARF expressions and location descriptions (see Section{locationdescriptions}) are evaluated within acontext provided by the debugger or other DWARF consumer.The context includes the following elements:

1. Required result kind

   The kind of result required – either a location or a value – isdetermined by the DWARF construct where the expression is found.

   For example, DWARF attributes with exprval classrequire a value, and attributes with locdesc exprloc class requirea location description (see Section {classesandforms}).

2. Initial stack

   In most cases, the DWARF expression stack is empty atthe start of expression evaluation. In certaincircumstances, however, one or morevalues entries are pushedimplicitly onto the stack before evaluation of theexpression starts (e.g., DW_AT_data_member_location).

3. Current compilation unit

   The current compilation unit is the compilation unit debugginginformation entry that contains the DWARF expression being evaluated.

   A current compilation unit is required for operations that referencedebug information associated with the same compilation unit, includingindicating if such references use the 32-bit or 64-bit DWARF format.

   For example, the DW_OP_constx and DW_OP_addrx operationsrequire the address size, which is a property of the compilation unit.

   Note that this compilation unit might not be the same as thecompilation unit determined from the loaded code object correspondingto the current program location. For example, the evaluation of theexpression E associated with a DW_AT_location attribute of the debuginformation entry operand of the DW_OP_call<n> operations is evaluatedwith the compilation unit that contains E and not the one that containsthe DW_OP_call<n> operation expression.

4. Target architecture

   The target architecture is typically provided by the object filecontaining the DWARF information. It may also be refined by instructionset identifiers in the line number table.

   The target architecture is required for operations that specifyarchitecture-specific entities.

   Architecture-specific entities include DWARF register identifiers,DWARF address space identifiers, the default address space, and theaddress space address sizes.

5. Current thread

   Many programming environments support the concept of independentthreads of execution, where the process and its address space are sharedamong the threads, but each thread has its own stack, program counter,and possibly its own block of memory for thread-local storage (TLS).These threads may be implemented in user-space or with kernel threads,or by a combination of the two.

   The current thread identifies a current thread of execution. Whendebugging a multi-threaded program, the current thread may be selectedby a user command that focuses on a specific thread, or it may be selectedautomatically when the running thread stops at a breakpoint.

   If there is no current process (or an image of a process, as froma core file), there is no current thread.

   A current thread is required for the DW_OP_form_tls_addressDW_OP_form_tls_location operation(see Section {stackoperations}) which provides access tothread-local storage.

6. Current call frame

   The current call frame identifies an active invocation of a subprogram.It is identified by its address on the call stack (see Section{framebase}). The address is referred to as the frame baseor the call frame address (CFA). The call frame information is used todetermine the base addresses for the call frames of the current thread’scall stack (see Section {callframeinformation}).

   When debugging a running program or examining a core file,the current frame may be the topmost (most recently activated) frame(e.g., where a breakpoint has triggered), or may be selected by a usercommand to focus the view on a frame further down the call stack.The current frame provides a view of the state of the running processat a particular point in time.

   The current call frame (if there is one) must be an active call framein the current call stack.

   A current call frame is required for operations that use the contentsof registers (e.g., DW_OP_reg<n>) or frame-local storage (e.g., DW_OP_fbreg)so that the debugger can retrieve values from the selected view of theprocess state.

7. Current lane

   On SIMD (Single-Instruction Multiple-Data Stream) and SIMT(Single-Instruction Multiple-Thread) architectures, fine-grained parallelexecution can be achieved by dispatching a single instruction acrossmultiple data streams (e.g., a vector or array). Some parallel programmingmodels allow for the vectorization of loops using SIMD instructions.These parallel streams can be considered fine-grain threads of execution,or lanes, where all lanes typically share a common stack, program counter,and register file.

   In SIMT architectures, control flow may diverge through the use ofpredication, where each instruction executes only in certain lanes. SomeSIMT architectures, however, provide separate stacks and register filesfor each lane, and the parallel streams of execution may instead berepresented as threads (above).

   The current lane is a SIMD/SIMT lane identifier. This applies to sourcelanguages with scalar code that is vectorized by the compiler using aSIMD/SIMT execution model. These implementations map vectorized operationsto SIMD/SIMT lanes of execution (see Section {lanesinsimdvectorization}).When debugging a SIMD/SIMT program, the current lane is typically selectedby a user command that focuses on a specific lane.

   The current lane number must be consistent with the value of the DW_AT_num_lanesattribute of the subprogram corresponding to the current frame and programlocation. It is consistent if the lane number is greater than or equal to 0 andless than the, possibly default, value of the DW_AT_num_lanes attribute.

   If the current program is not using a SIMD/SIMT execution model, the currentlane is always 0.

   A current lane is required for the DW_OP_push_lane operation (see Section{stackoperations}), which pushes the value of the current lane.

8. Current program counter (PC)

   The current program counter (PC) identifies the current point of executionin the current call frame.

   The PC in each call frame is the address of the next instruction to beexecuted in that frame. For the top (most recent) frame on the call stack,this is where execution would resume; for frames lower on the stack, itis where the callee will return. The call frame information is used toobtain the value of the return address register to determine the PC ofthe other call frames (see Section {callframeinformation}).

   If there is no current frame, there is no current PC.

   The current PC is used during the evaluation of value lists and locationlists to select from among multiple program location ranges.

   When evaluating value lists and location lists when no current PCis available, only default location descriptionsvalue or location list entries may be used.

9. Current object

   The current object is a data object described by a data object entry(see Section {dataobjectentries}) that is being inspected.When evaluating expressions that provide attribute values of a data object,the containing debugging information entry is the current object. Whenevaluating expressions that provide attribute values for a type (e.g.,DW_AT_data_location for a DW_TAG_member), the current object is the dataobject entry (if there is one) that referred to the type entry (e.g.,via DW_AT_type).

   A current object is required for theDW_OP_push_object_addressDW_OP_push_object_location(see Section {stackoperations}) operation and isimplicitly defined by some attributes (e.g.,DW_AT_data_member_location and DW_AT_use_location) where theobject’s location is provided as part of the initial stack.

A DWARF expression for a location description may be able to beevaluated without a thread, call frame, lane, program counter, or architecturecontext element. For example, the location of a global variable may be ableto be evaluated without such context, while the location of local variablesin a stack frame cannot be evaluated without additional context.

2.5.2 General Operations [REMOVED]

Each general operation represents a postfix operation ona simple stack machine.Each element of the stack has a type and a value, and can representa value of any supported base type of the target machine. Instead ofa base type, elements can have a generic type,which is an integral type that has thesize of an address on the target machine andunspecified signedness. The value on the top of the stack after “executing” theDWARF expression is taken to be the result (the address of the object, thevalue of the array bound, the length of a dynamic string,the desired value itself, and so on).

The generic type is the same as the unspecified type used for stack operationsdefined in DWARF Version 4 and before.

2.5.2.3 3.2 Stack Operations

The followingoperations manipulate the DWARF stack,and mayoperate on both values and locations.Operations that index the stack assume that the top of the stack (mostrecently added entry) has index 0.

Each entry on the stack has an associated typeis either a value (with an associated type) ora location.

1. DW_OP_dup
   The DW_OP_dup operation duplicates the value (including itstype identifier)entry at the top of the stack.

2. DW_OP_drop
   The DW_OP_drop operation pops the value (including its typeidentifier) entry at the top of the stack.

3. DW_OP_pick
   The single operand of the DW_OP_pick operation provides a1-byte index. A copy of the stack entry (including itstype identifier) with the specifiedindex (0 through 255, inclusive) is pushed onto the stack.

4. DW_OP_over
   The DW_OP_over operation duplicates the entry currently secondin the stack at the top of the stack.This is equivalent to aDW_OP_pick operation, with index 1.

5. DW_OP_swap
   The DW_OP_swap operation swaps the top two stack entries.The entry at the top of the stack (including its type identifier)becomes the second stack entry, and the second entry (includingits type identifier) becomes the top of the stack.

6. DW_OP_rot
   The DW_OP_rot operation rotates the first three stackentries. The entry at the top of the stack (including itstype identifier) becomes the third stack entry, the secondentry (including its type identifier) becomes the top ofthe stack, and the third entry (including its type identifier)becomes the second entry.

Examples illustrating many of these stack operations arefound in Appendix {dwarfstackoperationexamples}.

2.5.2.1 3.3 Literal Encodings and Constant Operations

The following operations all push a value onto the DWARF stack.Operations other than DW_OP_const_type push a value with thegeneric type, and if the value of a constant in one of theseoperations is larger than can be stored in a single stack element,the value is truncated to the element size and the low-order bitsare pushed on the stack.

1. DW_OP_lit0, DW_OP_lit1, …, DW_OP_lit31
   The DW_OP_lit<n> operations encode the unsigned literal valuesfrom 0 through 31, inclusive.

2. DW_OP_const1u, DW_OP_const2u, DW_OP_const4u, DW_OP_const8u
   The single operand of a DW_OP_const<n>u operation provides a 1,2, 4, or 8-byte unsigned integer constant, respectively.

3. DW_OP_const1s, DW_OP_const2s, DW_OP_const4s, DW_OP_const8s
   The single operand of a DW_OP_const<n>s operation provides a 1,2, 4, or 8-byte signed integer constant, respectively.

4. DW_OP_constu
   The single operand of the DW_OP_constu operation providesan unsigned LEB128 integer constant.

5. DW_OP_consts
   The single operand of the DW_OP_consts operation providesa signed LEB128 integer constant.

6. DW_OP_constx
   The DW_OP_constx operation has a single operand thatencodes an unsigned LEB128 value,which is a zero-basedindex into the .debug_addr section, where a constant, thesize of a machine addressthe generic type, is stored.This index is relative to the value of theDW_AT_addr_base attribute of the associated compilation unit.

   The DW_OP_constx operation is provided for constants thatrequire link-time relocation but should not beinterpreted by the consumer as a relocatable address(for example, offsets to thread-local storage).

7. DW_OP_const_type
   The DW_OP_const_type operation takes three operands. The first operandis an unsigned LEB128 integer that represents the offset of a debugginginformation entry in the current compilation unit, which must be aDW_TAG_base_type entry that provides the type of the constant provided. Thesecond operand is a 1-byte unsigned integer that specifies the size of theconstant value, which is the same as the size of the base type referencedby the first operand. The third operand is asequence of bytes of the given size that isinterpreted as a value of the referenced type.

   While the size of the constant can be inferred from the base typedefinition, it is encoded explicitly into the operation so that theoperation can be parsed easily without reference to the .debug_infosection.

2.5.2.2 3.4 Register Value Operations

The following operations pusha value onto the stack that is either part or all ofthe contents of a register or the result of adding the contents of aregister to a given signed offset onto the stack.DW_OP_regval_type pushes the contents of aregister together with the given base type.DW_OP_regval_bits pushes the partial contents ofa register together with the generic type.The other operationspush the result of adding the contents of a register to a givensigned offset together with the generic type.

1. DW_OP_regval_type
   The DW_OP_regval_type operationpushesthe contents ofa given register interpreted as a value of a given type. The firstoperand is an unsigned LEB128 number,which identifies a register whose contents is tobe pushed onto the stack. The second operand is an unsigned LEB128 numberthat represents the offset of a debugging information entry in the currentcompilation unit, which must be a DW_TAG_base_type entry that provides thetype of the value contained in the specified register.

2. DW_OP_regval_bits
   The DW_OP_regval_bits operation takes a single unsigned LEB128integer operand, which gives the number of bits to read. This number mustbe smaller or equal to the bit size of the generic type. It popsthe top two stack elements and interprets the top element as anunsigned bit offset from the least significant bit end and theother as a register number identifying the register from which toextract the value. If the extracted value is smaller than the sizeof the generic type, it is zero extended.

2.5.2.4 3.5 Arithmetic and Logical Operations

The following provide arithmetic and logical operations.The operations in this section take one or two stack operands,which must be values.Operands of an operation with two operandsmust have the same type,either the same base type or the generic type.The result of the operation which is pushed back has the same typeas the type of the operand(s).

If the type of the operands is the generic type,except as otherwise specified, the arithmetic operationsperform addressing arithmetic, that is, unsigned arithmetic that is performedmodulo one plus the largest representable address.

Operations other than DW_OP_abs,DW_OP_div, DW_OP_minus, DW_OP_mul, DW_OP_neg and DW_OP_plusrequire integral types of the operand (either integral base typeor the generic type). Operations do not cause an exceptionon overflow.

1. DW_OP_abs
   The DW_OP_abs operation pops the top stack entry, interpretsit as a signed value and pushes its absolute value. If theabsolute value cannot be represented, the result is undefined.

2. DW_OP_and
   The DW_OP_and operation pops the top two stack values, performsa bitwise and operation on the two, and pushes the result.

3. DW_OP_div
   The DW_OP_div operation pops the top two stack values, divides the former second entry bythe former top of the stack using signed division, and pushes the result.

4. DW_OP_minus
   The DW_OP_minus operation pops the top two stack values, subtracts the former top of thestack from the former second entry, and pushes the result.

5. DW_OP_mod
   The DW_OP_mod operation pops the top two stack values and pushes the result of thecalculation: former second stack entry modulo the former top of the stack.

6. DW_OP_mul
   The DW_OP_mul operation pops the top two stack entries, multiplies them together, andpushes the result.

7. DW_OP_neg
   The DW_OP_neg operation pops the top stack entry, interpretsit as a signed value and pushes its negation. If the negationcannot be represented, the result is undefined.

8. DW_OP_not
   The DW_OP_not operation pops the top stack entry, and pushesits bitwise complement.

9. DW_OP_or
   The DW_OP_or operation pops the top two stack entries, performsa bitwise or operation on the two, and pushes the result.

10. DW_OP_plus
    The DW_OP_plus operation pops the top two stack entries,adds them together, and pushes the result.

11. DW_OP_plusuconst
    The DW_OP_plusuconst operation pops the top stack entry,adds it to the unsigned LEB128constant operandinterpreted as the same type as the operand popped from thetop of the stack and pushes the result.

    This operation is supplied specifically to beable to encode more field offsets in two bytes than can bedone with“DW_OP_lit<n> DW_OP_plus”.

12. DW_OP_shl
    The DW_OP_shl operation pops the top two stack entries,shifts the former second entry left (filling with zero bits)by the number of bits specified by the former top of the stack,and pushes the result.

13. DW_OP_shr
    The DW_OP_shr operation pops the top two stack entries,shifts the former second entry right logically (filling withzero bits) by the number of bits specified by the former topof the stack, and pushes the result.

14. DW_OP_shra
    The DW_OP_shra operation pops the top two stack entries,shifts the former second entry right arithmetically (dividethe magnitude by 2, keep the same sign for the result) bythe number of bits specified by the former top of the stack,and pushes the result.

15. DW_OP_xor
    The DW_OP_xor operation pops the top two stack entries,performs a bitwise exclusive-or operation on the two, andpushes the result.

3.6 Context Query Operations

The following operations can be used to push a valueor location obtained from the expression evaluation context (see Section 3.1)onto the stack:

1. DW_OP_push_object_address DW_OP_push_object_location
   The DW_OP_push_object_address operation pushes theaddress of the object currently being evaluated as part ofevaluation of a user presented expression (see Section{dwarfexpressionevaluationcontext}). This object may correspond toan independent variable described by its own debugging informationentry or it may be a component of an array, structure, or classwhose address has been dynamically determined by an earlier stepduring user expression evaluation.

   The DW_OP_push_object_location operation pushes the location of thecurrent object (see Section 3.1) onto the stack, as part of evaluation of a userpresented expression.

   This object may correspond to an independentvariable described by its own debugging information entry; or it may be acomponent of an array, structure, or class whose address has beendynamically determined by an earlier step during user expressionevaluation.

   This operator provides explicit functionality (especially forarrays involving descriptors) that is analogous to the implicit pushof the base address of a structure prior to evaluation of aDW_AT_data_member_location to access a data member of a structure. Foran example, see Appendix D.2.

   In previous versions of DWARF, this operator was named DW_OP_push_object_address.The old name is still supported in DWARF 6 for compatibility.

2. DW_OP_form_tls_address DW_OP_form_tls_location
   The DW_OP_form_tls_addressDW_OP_form_tls_locationoperation pops a value from the stack,which must have an integral type identifier,translates this value intoan address a locationin the thread-local storage for the current thread(see Section 3.1), and pushes theaddress locationonto the stack together with the generic type identifier.The meaning of the value on the top of the stack prior to thisoperation is defined by the run-time environment. If the run-timeenvironment supports multiple thread-local storage blocks for asingle thread, then the block corresponding to the executable orshared library containing this DWARF expression is used.

   Some implementations of C, C++, Fortran, and other languages,support a thread-local storage class. Variables with this storageclass have distinct values and addresses in distinct threads, muchas automatic variables have distinct values and addresses in eachfunction invocation. Typically, there is a single block of storagecontaining all thread-local variables declared in the mainexecutable, and a separate block for the variables declared in eachshared library. Each thread-local variable can then be accessed inits block using an identifier. This identifier is typically anoffset into the block and pushed onto the DWARF stack by one of theDW_OP_const<n><x> operations prior to theDW_OP_form_tls_addressDW_OP_form_tls_locationoperation. Computing the address of the appropriate block can becomplex (in some cases, the compiler emits a function call to doit), and difficult to describe using ordinary DWARF locationdescriptions expressions.Instead of forcing complex thread-local storagecalculations into the DWARF expressions, theDW_OP_form_tls_addressDW_OP_form_tls_location operationallows the consumer to perform the computation based on the run-timeenvironment.

   In previous versions of DWARF, this operator was named DW_OP_form_tls_address.The old name is still supported in DWARF 6 for compatibility.

3. DW_OP_call_frame_cfa
   The DW_OP_call_frame_cfa operation pushes the value of thecurrent call frame address (CFA),obtained from the Call Frame Information(see Section {dwarfexpressionevaluationcontext} andSection {callframeinformation}).

   Although the value of DW_AT_frame_basecan be computed using other DWARF expression operators,in some cases this would require an extensive location listbecause the values of the registers used in computing theCFA change during a subroutine. If theCall Frame Informationis present, then it already encodes such changes, and it isspace efficient to reference that.

4. DW_OP_push_lane
   The DW_OP_push_lane operation pushes a lane index valueof the generic type, which provides the context of the lane inwhich the expression is being evaluated (seeSection {dwarfexpressionevaluationcontext} andSection {lowlevelinformation}).

2.6.1.1.2 3.7 Memory Locations

A memory location represents the location of a piece or all of anobject or other entity in memory. On architectures that supportmultiple address spaces, a memory location identifiesstorage associated with the address space.

In contexts that expect a location, a value of the generic typewill be implicitly converted to a memory location in the defaultaddress space.

The following operations push memory locations onto the stack:

1. DW_OP_addr
   The DW_OP_addr operation has a single operand that encodesa machine address and whose size is the size of an addresson the target machine.The value of this operand is treated as an addressin the default address space and the corresponding memory location ispushed onto the stack.

2. DW_OP_addrx
   The DW_OP_addrx operation has a single operand thatencodes an unsigned LEB128 value,which is a zero-based index into the .debug_addr section,where a machine address is stored.This index is relative to the value of theDW_AT_addr_base attribute of the associated compilation unit.The address obtained is treated as an address in the default addressspace and the corresponding memory location is pushed onto the stack.

3. DW_OP_fbreg
   The DW_OP_fbreg operation provides asigned LEB128 byte offset Bfrom the address locationspecified by the location description expression in theDW_AT_frame_base attribute of the current function(see Section 3.1).The frame base location, offset by B bytes,is pushed onto the stack.

   This is typically a stack pointer register plus or minus some offset.

4. DW_OP_breg0, DW_OP_breg1, …, DW_OP_breg31
   The single operand of the DW_OP_breg<n> operations provides a signedLEB128 offset from the contents of the specified registerbyte offset. The contents of the specified register (0–31) aretreated as a memory address in the default address space. The offset isadded to the address obtained from the register and the resulting memorylocation is pushed onto the stack.

5. DW_OP_bregx
   The DW_OP_bregx operation provides the sum of two values specifiedby its two operands. The first operand is a register numberwhich is specified by an unsigned LEB128number. The second operand is a signed LEB128 offset.
   The DW_OP_bregx operation has two operands. The firstoperand is a register number which is specified by an unsigned LEB128number. The second operand is a signed LEB128 byte offset. It is the same asDW_OP_breg<n> except it uses the register and offset provided by theoperands.

2.6.1.1.3 3.8 Register Locations

A register location description consists of a register nameoperation, which represents a piece or all of an objectlocated in a given register.

Register location descriptions describe an object(or a piece of an object) that resides in a register, whilethe opcodes listed in Section {registervalues}are used to describe an object (or a piece ofan object) that is located in memory at an address that iscontained in a register (possibly offset by some constant).A register location description must stand alone as the entiredescription of an object or a piece of an object.

The following DWARF operations can be used tospecify a register location.

Note that the register number represents a DWARF specificmapping of numbers onto the actual registers of a givenarchitecture. The mapping should be chosen to gain optimaldensity and should be shared by all users of a givenarchitecture. It is recommended that this mapping be definedby the ABI authoring committee for each architecture.

1. DW_OP_reg0, DW_OP_reg1, …, DW_OP_reg31
   The DW_OP_reg<n> operations encode the names of up to 32registers, numbered from 0 through 31, inclusive. The objectaddressed is in register n.A location that names the storage associated with the designated register,with an offset of 0, is formed and pushed on the stack.

2. DW_OP_regx
   The DW_OP_regx operation has a singleunsigned LEB128 literaloperand that encodes the name of a register.A location that names the storage associated with the designated register,with an offset of 0, is formed and pushed on the stack.

These operations name a register location,not the contents of the register. Tofetch the contents of a register, it is necessary to useone of the register based addressing operations, such asDW_OP_bregx (Section 3.7),the register value operationDW_OP_regval_type (Section 3.4),or a DW_OP_reg operation followed by a derefencing operation(Section 3.13).

2.6.1.1.1 3.9 Undefined Locations

An empty location description consists of a DWARF expression containingno operations. It represents a piece or all of an object that is presentin the source but not in the object code (perhaps due to optimization).

An undefined location represents a pieceor all of an object that is present in the source but not inthe object code (perhaps due to optimization).An undefined location cannot be read.Writing to undefined storage has no effect.

1. DW_OP_undefined
   The DW_OP_undefined operation pushes an undefinedlocation with an offset of 0 onto the stack.

2. A DWARF expression containing no operations orthat leaves no elements on the stack also produces an undefined location.This is for compatibility with earlier versions of DWARF.

2.6.1.1.4 3.10 Implicit Locations

DWARF location descriptions expressionsare intended to yield the location of avalue rather than the value itself. An optimizing compiler may perform anumber of code transformations where it becomes impossible to give alocation for a value, but it remains possible to describe the valueitself. Section 3.8 describes operators thatcan be used to describe the location of a value when that value existsin a register but not in memory. The operations in this section are usedto describe values that exist neither in memory nor in a singleregister.

An implicit location descriptionrepresents a piece or allof an object which has no actual location but whose contentsare nonetheless either known or known to be undefinedknown.

The following DWARF operations may be used to specify a valuethat has no location in the program but is a known constantor is computed from other locations and values in the program.

1. DW_OP_implicit_value
   The DW_OP_implicit_value operation specifies an immediate valueusing two operands: an unsigned LEB128 length, followed by asequence of bytes of the given length that contain the value.A location L is formed for a block of implicitstorage which contains the given byte sequence.The offset of L is set to 0, and L is pushed onto the stack.

2. DW_OP_stack_value
   The DW_OP_stack_valueoperation specifies that the objectdoes not exist in memory but its value is nonetheless knownand is at the top of the DWARF expression stack. In this formof location description, the DWARF expression represents theactual value of the object, rather than its location.The DW_OP_stack_value operation terminates the expression.The value V on top of the stack is popped, anda location L is formed for a block of implicit storagecontaining the value V, represented using the encoding and byte order ofthe value’s type.The offset of L is set to 0 and L is pushed onto the stack.

3.11 Implicit Pointer Locations [NEW]

An optimizing compiler may eliminate a pointer, while stillretaining the value object that thepointer addressed. DW_OP_implicit_pointer allows aproducer to describe this value the location(or value) of the latter object.

An implicit pointer location is used to describea pointer object P that cannot be represented as areal pointer, even though the locationor value of the object it would point to can bedescribed. In this form of location description, theDWARF expression It refers to a debugginginformation entry that represents the actual value of theobject V to which the pointer wouldpoint. Thus, a consumer of the debug information would beable to show the value of the dereferenced pointer, evenwhen it cannot show the value of the pointer itself.

The following DWARF operation is used to create an implicitpointer location:

1. DW_OP_implicit_pointer

   The DW_OP_implicit_pointer operation has twooperands: a reference to a debugging information entrythat describes the dereferenced object’s value, and asigned number that is treated as a byte offset from thestart of that value. The first operand is a 4-byteunsigned value in the 32-bit DWARF format, or an 8-byteunsigned value in the 64-bit DWARF format (see Section{32bitand64bitdwarfformats}) that is used as the offsetof a debugging information entry in the .debug_infosection of the current executable or shared object file.The second operand is a signed LEB128 number.

   The debugging information entry referenced by aDW_OP_implicit_pointer operation is typically aDW_TAG_variable or DW_TAG_formal_parameter entry whoseDW_AT_location attribute gives a second DWARF expression or alocation list that describes the valueof the object, but thereferenced entry may be any entry that contains a DW_AT_locationor DW_AT_const_value attribute (for example, DW_TAG_dwarf_procedure).By using the second DWARF expression, a consumer canreconstruct the value of the object when asked to dereferencethe pointer described by the original DWARF expressioncontaining the DW_OP_implicit_pointer operation.

   The DW_OP_implicit_pointer operation has two operands.The first operand is a reference to a debugginginformation entry D. It is a 4-byte unsigned value inthe 32-bit DWARF format, or an 8-byte unsigned value inthe 64-bit DWARF format (see Section{32bitand64bitdwarfformats}) that is used as the offsetof the debugging information entry D in the.debug_info section of the current executable orshared object file. The second operand is a signedLEB128 number that is treated as a byte offset B.

   The debugging information entry D must contain aDW_AT_location attribute or a DW_AT_const_valueattribute. In the first case, the DW_AT_locationattribute is evaluated to obtain a location; in thesecond case, an implicit location is formed to hold theconstant value. The byte offset B is added to thatlocation and the resulting location is used as thelocation of the object V.

   A location L is formed for a block of implicitpointer storage, which describes the location of thepointer object P. The implicit pointer storagerepresents the location of the object V, and has thesize of the pointer that was optimized away. The offsetof L is set to 0, and L is pushed onto thestack.

   The debugging information entry D is typically aDW_TAG_variable or DW_TAG_formal_parameter entrywhose DW_AT_location attribute evaluates to thelocation of the object V, but it may be any entry thatcontains a DW_AT_location or DW_AT_const_valueattribute (for example, DW_TAG_dwarf_procedure). Thelocation of V would typically be an implicit value, aregister, or a composite location (an optimized-outpointer to a memory location could be described moresimply as an implicit value).

2.6.1.2 3.12 Composite Locations

A composite location description describes an object orvalue which may be contained in part of a register or storedin more than one location. Each piece is described by acomposition operation, which does not compute a value norstore any result on the DWARF stack. There may be one ormore composition operations in a single composite locationdescription. A series of such operations describes the parts of a valuein memory address order.

Each composition operation is immediately preceded by a simplelocation description which describes the location where partof the resultant value is contained.

A composite location represents the location of an object orvalue that does not exist in a single block of contiguousstorage (e.g., as the result of compiler optimization wherepart of the object is promoted to a register). Its storage consistsof a (possibly empty) sequence of pieces, where each piecemaps a fixed range of bits from the object onto acorresponding range of bits at a new (sub-)location.

The pieces of a block of composite storage are contiguous, so thatthe size of the composite storage is the sum of the sizesof the individual pieces, and each piece covers a range ofbits immediately following the previous piece.The maximum size of a block of composite storage isthe size of the largest address space or register.

Typically, the size of a composite storage is the same asthat of the object it describes. If the composite storageis smaller than the object, the remaining bits of the objectare treated as undefined.

In the process of fetching a value from a compositelocation, the consumer may need to fetch and assemble bits frommore than one piece.

The following operation is used to form a new, empty, composite location:

1. DW_OP_composite
   The DW_OP_composite operator has no operands. It pushes a new, empty,composite location onto the stack, with an offset of 0.

   This operator is provided so that a new series ofpiece operations can be started to form a composite location whenthe state of the stack is unknown (e.g., following a DW_OP_call*operation), or when a new composite is to be started (e.g., ratherthan add to a previous composite location on the stack).

The following operations are used to build a compositelocation in storage order, one piece at a time. Each pieceoperation expects a sub-location, L, at the top of thestack, and the composite location under construction, C,in the preceding element on the stack. It pops those twolocations and extends C by adding a new piece that mapsthe given number of bytes or bits to the sub-location L.The offset of the new location is the same as that of C.The new composite location is pushed onto the stack.

1. DW_OP_piece
   The DW_OP_piece operation takes asingle operand, which is anunsigned LEB128 number.The number describes the size, in bytes,of the piece of the objectreferenced by the preceding simple location descriptionto be appended to the composite C.

   If the piece is located in a register,the sub-location L is a register location,but the piece does not occupy the entire register,the placement of the piece within that register is defined by the ABI.

   Many compilers store a single variable in sets of registers,or store a variable partially in memory and partially inregisters. DW_OP_piece provides a way of describing how largea part of a variable a particular DWARF location descriptionrefers to.

2. DW_OP_bit_piece
   The DW_OP_bit_piece operation takes two operands.The first is an unsigned LEB128 number that gives the size, in bits,of the piece to be appended.The second is an unsigned LEB128 number thatgives the offset in bitsfrom the location defined by the preceding DWARF location descriptionto be applied to the sub-location L.

   Interpretation of the offset depends on the location description.If the location description isempty an undefined location (see Section {undefinedlocations}),the DW_OP_bit_piece operationdescribes a piece consisting of the given number of bits whose valuesare undefined, and the offset is ignored.If the location is a memoryaddress location (see Section {memorylocationdescriptions})or a composite location,the DW_OP_bit_piece operation describes asequence of bits relative to the location whose address ison the top of the DWARF stack using the bit numbering anddirection conventions that are appropriate to the currentlanguage on the target system.In all other cases, the source of the piece is given by either aregister location (see Section {registerlocationdescriptions}) or animplicit value description location(see Section {implicitlocationdescriptions});the offset is from the least significant bit of the source value.

   DW_OP_bit_piece isused instead of DW_OP_piece whenthe piece to be assembled into a value or assigned to is notbyte-sized or is not at the start of a register or addressableunit of memory.

   Whether or not a DW_OP_piece operation is equivalent to anyDW_OP_bit_piece operation with an offset of 0 is ABI dependent.

A composition operation that follows an empty location description indicatesthat the piece is undefined, for example because it has been optimized away.

For compatibility with DWARF Version 5 and earlier, the followingexceptions apply to the piece operations:

• If L is a non-composite location (or convertible toone) and is the only element on the stack, the resultis a new composite location with the single piece L (asif DW_OP_composite DW_OP_swap had been processedimmediately prior to the piece operation).This rule supports the first piece operation in a DWARF 5 expression.

• If a piece operation is processed while the stack is empty, a newempty composite and an undefined location are pushed implicitly (as ifDW_OP_composite DW_OP_undefined had been processed immediately priorto the piece operation). The result is a composite with a singleundefined piece.This rule supports the empty piece operation in DWARF 5 when it is thefirst piece of a composite.

• If the top of the stack is a composite location, and isthe only element on the stack, an undefined location ispushed implicitly (as if DW_OP_undefined had beenprocessed immediately prior to the piece operation),whereupon the composite on top of the stack is taken asC and the undefined location is L. The result is theaddition of an undefined piece to the existing compositelocation.This rule supports the empty piece operation in DWARF 5 when it is not thefirst piece of a composite.

3.13 Dereferencing Operations [NEW]

The following operations are used to dereference a locationon the stack; i.e., to load a value (or another location) stored at that location.Each operation defines the number of bytes or bits to be loaded.

Dereferencing a memory location simply loads a value from memory.Dereferencing a register location extracts all or some of the bits from the register,depending on the offset of the location and the size of value to be loaded.Dereferencing an implicit location loads a value (or, inthe case of an implicit pointer, another location) fromthe implicit storage. Attempting to dereference anundefined location is an error.

When dereferencing from a composite location, the value to be loadedmay span more than one of the pieces of the composite, and theconsumer must reassemble the value from the component pieces.

1. DW_OP_deref
   The DW_OP_deref operation pops the top stack entry andtreats it as an address. The popped value must have an integral type.The value retrieved from that address is pushed,and has the generic type.The size of the data retrieved from thedereferencedaddress is the size of an address on the target machine.

   The DW_OP_deref operation pops a location L from the top of thestack. The first S bits, where S is the size (in bits) of an address on thetarget machine, are retrieved from the location L and pushed onto thestack as a value of the generic type.

   If the location on the stack is an implicit pointer (see Section 3.11),the location LP is dereferenced to obtain the location LV.In this case, the offset of the location LP must be 0.

2. DW_OP_deref_size
   The DW_OP_deref_size operation behaves like theDW_OP_derefoperation: it pops the top stack entry and treats it as anaddress. The popped value must have an integral type.The value retrieved from that address is pushed,and has the generic type.In the DW_OP_deref_size operation, however, the size in bytesof the data retrieved from the dereferenced address isspecified by the single operand. This operand is a 1-byteunsigned integral constant whose value may not be largerthan the size of the generic type. The dataretrieved is zero extended to the size of an address on thetarget machine before being pushed onto the expression stack.
   The DW_OP_deref_size takes a single 1-byte unsigned integral operandthat specifies the size S, in bytes, of the value to be retrieved.The size S must be no larger than the size of the generic type. Theoperation behaves like the DW_OP_deref operation: it pops a locationL from the stack. The first S bytes are retrieved from thelocation L, zero extended to the size of the generic type, andpushed onto the stack as a value of the generic type.

3. DW_OP_deref_type
   The DW_OP_deref_type operation behaves like the DW_OP_deref_size operation:it pops the top stack entry and treats it as an address.The popped value must have an integral type.The value retrieved from that address is pushed together with a type identifier.In the DW_OP_deref_type operation, the size inbytes of the data retrieved from the dereferenced address is specified bythe first operand. This operand is a 1-byte unsigned integral constant whosevalue which is the same as the size of the base type referencedby the second operand.The second operand is an unsigned LEB128 integer thatrepresents the offset of a debugging information entry in the currentcompilation unit, which must be a DW_TAG_base_type entry that provides thetype of the data pushed.
   The DW_OP_deref_type operation takes two operands. The first operandis a 1-byte unsigned integer that specifies the byte size S of the typegiven by the second operand. The second operand is an unsigned LEB128integer that represents the offset of a debugging information entry inthe current compilation unit, which must be a DW_TAG_base_type entrythat provides the type T of the value to be retrieved. The size Smust be the same as the byte size of the base type represented by thetype T. This operation pops a location L from the stack. Thefirst S bytes are retrieved from the location L and pushed onto thestack as a value of type T.

   While the size of the pushed value could be inferred from the basetype definition, it is encoded explicitly into the operation so that theoperation can be parsed easily without reference to the .debug_infosection.

4. DW_OP_xderef
   The DW_OP_xderef operation provides an extended dereferencemechanism. The entry at the top of the stack is treated as anaddress. The second stack entry is treated as an “addressspace identifier” for those architectures that supportmultipleaddress spaces.Both of these entries must have integral types identifiers.The top two stack elements are popped,and a data item is retrieved through an implementation-definedaddress calculation and pushed as the new stack top together with thegeneric type identifier.The size of the data retrieved from thedereferencedaddress is the size of the generic type.

5. DW_OP_xderef_size
   The DW_OP_xderef_size operation behaves like theDW_OP_xderef operation. The entry at the top of the stack istreated as an address. The second stack entry is treated asan “address space identifier” for those architecturesthat supportmultipleaddress spaces.Both of these entries must have integral types identifiers.The top two stackelements are popped, and a data item is retrieved through animplementation-defined address calculation and pushed as thenew stack top. In the DW_OP_xderef_size operation, however,the size in bytes of the data retrieved from thedereferencedaddress is specified by the single operand. This operand is a1-byte unsigned integral constant whose value may not be largerthan the size of an address on the target machine. The dataretrieved is zero extended to the size of an address on thetarget machine before being pushed onto the expression stack togetherwith the generic type identifier.

6. DW_OP_xderef_type
   The DW_OP_xderef_type operation behaves like the DW_OP_xderef_sizeoperation: it pops the top two stack entries, treats them as an address andan address space identifier, and pushes the value retrieved. In theDW_OP_xderef_type operation, the size in bytes of the data retrieved fromthe dereferenced address is specified by the first operand. This operand isa 1-byte unsigned integral constant whose valuevalue which is the same as the size of the base type referencedby the second operand. The secondoperand is an unsigned LEB128 integer that represents the offset of adebugging information entry in the current compilation unit, which must be aDW_TAG_base_type entry that provides the type of the data pushed.

3.14 Offset Operations [NEW]

In addition to the composite operations, locationsmay be modified by the following operations:

1. DW_OP_offset
DW_OP_offset pops two stack entries. The first (top of stack)must be an integral type value, which represents a signed bytedisplacement. The second must be a location. It forms an updatedlocation by adding the given byte displacement to the offsetcomponent of the original location and pushes the updated locationonto the stack.

2. DW_OP_bit_offset
DW_OP_bit_offset pops two stack entries. The first(top of stack) must be an integral type value, which represents a signed bitdisplacement. The second must be a location. It forms an updatedlocation by adding the given bit displacement to the offsetcomponent of the original location and pushes the updated locationonto the stack.

   A bit offset of N × byte_size is equivalent to a byte offset of N.

The resulting offset must remain valid for the location.

2.5.2.5 3.15 Control Flow Operations

The following operations provide simple control of the flow of a DWARF expression.

1. DW_OP_le, DW_OP_ge, DW_OP_eq, DW_OP_lt, DW_OP_gt, DW_OP_ne
   The six relational operators each:

   • pop the top two stack values, which have the same type,either the same base type or the generic type,

   • compare the operands:
     <former second entry> <relational operator> <former top entry>

   • push the constant value 1 onto the stackif the result of the operation is true or theconstant value 0 if the result of the operation is false.The pushed value has the generic type.

   If the operands have the generic type, the comparisonsare performed as signed operations.

2. DW_OP_skip
DW_OP_skip is an unconditional branch. Its single operandis a 2-byte signed integer constant. The 2-byte constant isthe number of bytes of the DWARF expression to skip forwardor backward from the current operation, beginning after the2-byte constant.

3. DW_OP_bra
DW_OP_bra is a conditional branch. Its single operand is a2-byte signed integer constant. This operation pops thetop of stack. If the value popped is not the constant 0,the 2-byte constant operand is the number of bytes of theDWARF expression to skip forward or backward from the currentoperation, beginning after the 2-byte constant.

4. DW_OP_call2, DW_OP_call4, DW_OP_call_ref
DW_OP_call2, DW_OP_call4, and DW_OP_call_ref performDWARF procedure calls during evaluation of a DWARF expression orlocation description.For DW_OP_call2 and DW_OP_call4,the operand is the 2- or 4-byte unsigned offset, respectively,of a debugging information entry in the current compilationunit. The DW_OP_call_ref operator has a single operand. In the32-bit DWARF format,the operand is a 4-byte unsigned value;in the 64-bit DWARF format, it is an 8-byte unsigned value(see Section {32bitand64bitdwarfformats}).The operand is used as the offset of adebugging information entry inthe .debug_info section of the current executable or shared object file.

   Operand interpretation ofDW_OP_call2, DW_OP_call4 and DW_OP_call_ref is exactly likethat for DW_FORM_ref2, DW_FORM_ref4 and DW_FORM_ref_addr,respectively (see Section {attributeencodings}).

   These operations transfer control of DWARF expression evaluation tothe DW_AT_location attribute of the referenced debugging information entry. Ifthere is no such attribute, then there is no effect. Executionof the DWARF expression of a DW_AT_location attribute mayadd to and/or remove from values onpop elements from the stack and/or push values or locations ontothe stack.Execution returnsto the point following the call when the end of the attributeis reached. Values and locations on the stack at the time of the call may beused as parameters by the called expression, and valueselements (values or locations) left onthe stack by the called expression may be used as return valuesby prior agreement between the calling and called expressions.

2.5.2.6 3.16 Type Conversions

The following operations provide for explicit type conversion.The operand on top of the stack must be a value.

1. DW_OP_convert
   The DW_OP_convert operation pops the top stack entry, converts it to adifferent type, then pushes the result. It takes one operand, which is anunsigned LEB128 integer that represents the offset of a debugginginformation entry in the current compilation unit, or value 0 whichrepresents the generic type. If the operand is non-zero, thereferenced entry must be a DW_TAG_base_type entry that provides the typeto which the value is converted.

2. DW_OP_reinterpret
   The DW_OP_reinterpret operation pops the top stack entry, reinterpretsthe bits in its value as a value of a different type, then pushes theresult. It takes one operand, which is an unsigned LEB128 integer thatrepresents the offset of a debugging information entry in the currentcompilation unit, or value 0 which represents the generic type.If the operand is non-zero, the referenced entry must be aDW_TAG_base_type entry that provides the type to which the value isconverted reinterpreted.The type of the operand and result type must have the same size in bits.

2.5.2.7 3.17 Special Operations

There are these special operations currently defined:

1. DW_OP_nop
   The DW_OP_nop operation is a place holder. It has no effecton the location stack or any of itsvalues elements.

2. DW_OP_entry_value
   The DW_OP_entry_value operation pushesthe value thatan expression would have had, or a register location would have held,upon entering the current subprogram. It has two operands: anunsigned LEB128 length, followed bya block containing a DWARF expression or a register location description(see Section {registerlocationdescriptions}).The length operand specifies the length in bytes of the block.If the block contains a DWARF expression,the DWARF expression is evaluated as if it had been evaluated upon enteringthe current subprogram. The DWARF expressionassumes no values are present on the DWARF stack initially and resultsin exactly one value being pushed on the DWARF stack when completed.If the block contains a register locationdescription, DW_OP_entry_value pushes the value that registerheldupon entering the current subprogram.

   DW_OP_push_object_addressDW_OP_push_object_locationis not meaningful inside of this DWARF operation.

   The register location description provides a more compact form for thecase where the value was in a register on entry to the subprogram.

   The values needed to evaluate DW_OP_entry_value could be obtained inseveral ways. The consumer could suspend execution on entry to thesubprogram, record values needed by DW_OP_entry_value expressions withinthe subprogram, and then continue; when evaluating DW_OP_entry_value,the consumer would use these recorded values rather than the currentvalues. Or, when evaluating DW_OP_entry_value, the consumer couldvirtually unwind using the Call Frame Information(see Section {callframeinformation})to recover register values that might have been clobbered since thesubprogram entry point.

3. DW_OP_extended
   The DW_OP_extended opcode encodes an extension operation. It hasat least one operand: a ULEB128 constant identifying the extension operation.The remaining operands are defined by the extension opcode, which are namedusing a prefix of DW_OP_.The extension opcode 0 is reserved.

4. DW_OP_user_extended
   The DW_OP_user_extended opcode encodes aproducerextension operation.It has at least one operand: a ULEB128 constant identifying aproducerextension operation. The remaining operands are defined by theproducerextension. Theproducerextension opcode 0 is reserved and cannot be used by anyproducerextension.

   The DW_OP_user_extended encoding space can be understood to supplementthe space defined by DW_OP_lo_user and DW_OP_hi_user that is allocated bythe standardthis specification for the same purpose.

2.5.2 3.18 Value Lists

Value lists are used in place ofDWARF expressions whenever the value of an object’s attributecan change during the lifetime of that object.

Value lists are contained in a separate object file section,along with location lists (see {locationlists}).

A value list is indicated by an attribute whose value is of classvallist (see Section {classesandforms}).

A value list consists of a series of value list entries.The representation of a value list is the same as for alocation list (see {locationlists}), exceptthat bounded location description and default location descriptionentries are understood to provide DWARF expressions that producevalues rather than location descriptions.

The DWARF expressions in value list entries, beingexpressions and not location descriptions, may not containany of the DWARF operations described in Section{locationdescriptions}.

The address ranges defined by the bounded expressions of avalue list may overlap. When they do, the meaning is undefinedif the overlapping expressions do not produce the same value.

2.6.2 3.19 Location Lists

Location lists are used in place oflocation descriptionsexpressions wheneverthe object whose location is being described can change locationduring its lifetime.Location lists are contained in a separateobject file section called .debug_loclists or .debug_loclists.dwo(for split DWARF object files).

A location list is indicated by a location or otheran attribute whose value is of class loclist(see Section {classesandforms}).

This location list representation, the loclist class, and therelated DW_AT_loclists_base attribute are new in DWARF Version 5.Together they eliminate most or all of the object language relocationspreviously needed for location lists.

A location list consists of a series of location list entries.Each location list entry is one of the following kinds:

• Bounded location description.

  This kind of entry provides alocation description that specifies the location ofan object that is valid over a lifetime boundedby a starting and ending address. The starting address is thelowest address of the address range over which the locationis valid. The ending address is the address of the firstlocation past the highest address of the address range.When the current PC is within the given range, the locationdescription may be used to locate the specified object.The location description is valid even if the address rangeincludes addresses within a prologue or epilogue range.

  There are several kinds of bounded location descriptionentries which differ in the way that they specify thestarting and ending addresses.

  The address ranges defined by the bounded location descriptionsof a location list may overlap. When they do, they describe asituation in which an object exists simultaneously in more thanone place. If all of the address ranges in a given locationlist do not collectively cover the entire range over which theobject in question is defined, and there is no following defaultlocation description, it is assumed that the object is notavailable for the portion of the range that is not covered.

  In the case of a bounded location description where the range is definedby a starting address and either an ending address or a length, astarting address consisting of the reserved address value (see Section{reservedtargetaddress}) indicates a non-existent range,which is equivalent to omitting the description.

• Default location description.This kind of entry provides alocation description that specifies the location ofan object that is valid when no bounded location descriptionapplies.As with simple location descriptions, the lifetime of a defaultlocation excludes any prologue or epilogue ranges.

• Base address.This kind of entry provides an address to beused as the base address for beginning and ending addressoffsets given in certain kinds of bounded location description.The applicable base address of a bounded location descriptionentry is the address specified by the closest preceding baseaddress entry in the same location list. If there is nopreceding base address entry, then the applicable base addressdefaults to the base address of the compilation unit (seeSection {fullandpartialcompilationunitentries}).

  In the case of a compilation unit where all of the machinecode is contained in a single contiguous section, no baseaddress entry is needed.

  If the base address is the reserved target address, either explicitlyor by default, then the range of any bounded location descriptiondefined relative to that base address is non-existent, which isequivalent to omitting the description.

• End-of-list.This kind of entry marks the end of the location list.

A location list consists of a sequence of zero or more boundedlocation description or base address entries, optionally followedby a default location entry, and terminated by an end-of-listentry.

If there is no current PC (see Section{dwarfexpressionevaluationcontext}), only thedefault location list entry is used.

Each location list entry begins with a single byte identifyingthe kind of that entry, followed by zero or more operands dependingon the kind.

In the descriptions that follow, these terms are used for operands:

• A counted location description operand consists ofan unsigned ULEB integer giving the length of the locationdescription (see Section {singlelocationdescriptions})that immediately follows.

• An address index operand is the index of an addressin the .debug_addr section. This index is relative to thevalue of the DW_AT_addr_base attribute of the associatedcompilation unit. The address given by this kindof operand is not relative to the compilation unit base address.

• A target address operand is an address on the targetmachine. (Its size is the same as used for attribute values ofclass address, specifically, DW_FORM_addr.)

The following entry kinds are defined for use in bothsplit or non-split units:

1. DW_LLE_end_of_list
   An end-of-list entry contains no further data.

   A series of this kind of entry may be used for padding oralignment purposes.

2. DW_LLE_base_addressx
   This is a form of base address entry that has one unsignedLEB128 operand. The operand value is an address index (into the.debug_addr section) that indicates the applicable base addressused by subsequent DW_LLE_offset_pair entries.

3. DW_LLE_startx_endx
   This is a form of bounded location description entry(see page {bndlocdesc})that has two unsigned LEB128 operands. The operand values areaddress indices (into the .debug_addr section). These indicate thestarting and ending addresses, respectively, that definethe address range for which this location is valid.These operands are followed by a counted location description.

4. DW_LLE_startx_length
   This is a form of bounded location description entry(see page {bndlocdesc})that has two unsigned LEB128 operands. The first value is an address index(into the .debug_addr section)that indicates the beginning of the address range overwhich the location is valid.The second value is the length of the range.These operands are followed by a counted location description.

5. DW_LLE_offset_pair
   This is a form of {bounded location description} entry(see page {bndlocdesc})that has two unsigned LEB128 operands. The values of theseoperands are the starting and ending offsets, respectively,relative to the applicable base address, that define theaddress range for which this location is valid.These operands are followed by a counted location description.

6. DW_LLE_default_location
   The operand is a counted location description which defineswhere an object is located if no prior location descriptionis valid.

7. DW_LLE_include_loclistx
   This is a form of list inclusion, that has one unsigned LEB128operand. The value is an index into the .debug_loclists section,interpreted the same way as the operand of DW_FORM_loclistx to finda target list of entries, which will be regarded as part of thecurrent location list, up to the DW_LLE_end_of_list entry.

The following kinds of location list entries are defined foruse only in non-split DWARF units:

1. DW_LLE_base_address
   A base address entry has one target address operand.This address is used as the base address when interpretingoffsets in subsequent location list entries of kindDW_LLE_offset_pair.

2. DW_LLE_start_end
   This is a form of bounded location description entry(see page {bndlocdesc})that has two target address operands. These indicate thestarting and ending addresses, respectively, that definethe address range for which the location is valid.These operands are followed by a counted location description.

3. DW_LLE_start_length
   This is a form of bounded location description entry(see page {bndlocdesc})that has one target address operand value and an unsigned LEB128integer operand value. The address is the beginning addressof the range over which the location description is valid, andthe length is the number of bytes in that range.These operands are followed by a counted location description.

4. DW_LLE_include_loclist
   This is a form of list inclusion, that has one offset operand. Thevalue is an offset into the .debug_loclists section, like theoperand of DW_FORM_sec_offset. The offset identifies thefirst entry of a location list whose entries are to be regarded as part ofthe current location list, up to the DW_LLE_end_of_list entry.

Chapter 56: Type Entries

…

6.7 Structure, Union, Class and Interface Type Entries

…

6.7.6 Data Member Entries

…

For a DW_AT_data_member_location attribute there are two cases:

1. If the value is an integer constant, it is the offset in bytes from the beginningof the containing entity. If the beginning of the containing entity has anon-zero bit offset then the beginning of the member entry has that same bitoffset as well.

2. Otherwise, the value must be a locationdescription expression.In this case, thebeginning of the containing entity must be byte aligned.The beginning addresslocation of the containing entityis pushed on the DWARF stack before the locationdescription expression isevaluated; the result of the evaluation is thebase address location of the memberentry (see Section 2.5.1 on page 27 3.1).

   The push on the DWARF expression stack of the base address location of the containingconstruct is equivalent to execution of the DW_OP_push_object_addressDW_OP_push_object_location operation(see Section 2.5.2.33.6);DW_OP_push_object_addressDW_OP_push_object_locationtherefore is not needed at the beginning of a locationdescription expressionfor a data member. The result of the evaluation is alocation—either an address or the name of a register,not an offset to the member.

   A DW_AT_data_member_location attribute that has the form of a locationdescription is not valid for a data member contained in an entity that is not bytealigned because DWARF operations do not allow for manipulating or computing bitoffsets.

…

Section 6.7.8 Member Function Entries

…

An entry for a virtual function also has aDW_AT_vtable_elem_location attribute whose value contains alocation expression yielding the addresslocation of the slot forthe function within the virtual function table for theenclosing class. The addresslocation of an object of the enclosingtype is pushed onto the expression stack before the locationdescription expressionis evaluated.

…

6.14 Pointer to Member Type Entries

…

The pointer to member entry has a DW_AT_use_locationattribute whose value is a location descriptionexpressionthat computes the address of the member of the class to which thepointer to member entry points.

The method used to find the address of a given member of aclass or structure is common to any instance of that classor structure and to any instance of the pointer or membertype. The method is thus associated with the type entry,rather than with each instance of the type.

The DW_AT_use_location descriptionexpression is used in conjunction with thelocation descriptions expressions fora particular object of the given pointer to member type andfor a particular structure or class instance. TheDW_AT_use_location attribute expects two valueselements to be pushed onto the DWARF expressionstack before the DW_AT_use_location descriptionexpression is evaluated (see Section2.5.13.1). The first valueelement pushed is the value of the pointer to memberobject itself. The second value elementpushed is the base address location ofthe entire structure or union instance containing the memberwhose address location is beingcalculated.

Chapter 67: Other Debugging Information

…

7.4 Call Frame Information

…

7.4.1 Structure of Call Frame Information

…

The register rules are:

…

expression(E)
The previous value of this register is located at theaddress locationproduced by executing theDWARF expression E (see Section2.5 Chapter 3).

Chapter 78: Data Representation

…

8.5 Format of Debugging Information

…

8.5.5 Classes and Forms

…

• locdesc exprloc
  A DWARF location description expression(see Section 2.65).This is represented as an unsigned LEB128 length,followed by a byte sequence of the specified length(DW_FORM_locdescDW_FORM_expression)containing the location expression.