DWARF expressions describe how to compute a value or name a location during debugging of aprogram. They are expressed in terms of DWARF operations that operate on a stack of values.
All DWARF operations are encoded as a stream of opcodes that are each followed by zero ormore literal operands. The number of operands is determined by the opcode.
In addition to the general operations that are defined here, additional register name operations(which are specific to location expressions) are defined in Section 2.6.1.
In DWARF Version 2, all DWARF expressions were called “location expressions,” whether theycomputed a location (address, register) or not. This revision defines DWARF expressions as theprimary concept, and then defines location expressions as DWARF expressions that are used tocompute or name a location.
Each general operation represents a postfix operation on a simple stack machine. Each elementof the stack is the size of an address on the target machine. The value on the top of the stack after“executing” the DWARF expression is taken to be the result (the address of the object, the valueof the array bound, the length of a dynamic string, and so on).
Each general operation represents a postfix operation on a simple stack machine.Each element of the stack has a type and a value,and can represent a value of any supported base type of the target machine.The value on the top of the stack after“executing” the DWARF expression is taken to be the result (the address of the object, the valueof the array bound, the length of a dynamic string, and so on).
While the abstract definition of the stack calls for variable-size entries ableto hold any supported base type, in practice it is expected that each element of the stack canbe represented as a fixed-size element large enough to hold a value of any type supported by theDWARF consumer for that target, plus a small identifier sufficient to encode the type of that element.Support for base types other than what is required to do address arithmetic isintended only for debugging of optimized, and the completeness of the DWARF consumer'ssupport for the full set of base types is a quality-of-implementation issue.If a consumer encounters a DWARF expression that uses a type it does not support,it should ignore the entire expression and report its inability to provide the requested information.
It should also be noted that floating-point arithmetic is highlydependent on the computational environment. It is not the intention of this expressionevaluation facility to produce identical results to those produced by the programbeing debugged while executing on the target machine. Floating-point computationsin this stack machine will be done with precision control and rounding modesas defined by the implementation.
The following operations all push a value onto the DWARF stack.
DW_OP_lit0, DW_OP_lit1, ..., DW_OP_lit31
The DW_OP_litn operations encode the unsigned literal values from 0 through 31, inclusive.
DW_OP_addr
The DW_OP_addr operation has a single operand that encodes a machine address and whosesize is the size of an address on the target machine.
DW_OP_const1u
The single operand of the DW_OP_const1u operation provides a 1-byte unsigned integerconstant.
DW_OP_const1s
The single operand of the DW_OP_const1s operation provides a 1-byte signed integerconstant.
DW_OP_const2u
The single operand of the DW_OP_const2u operation provides a 2-byte unsigned integerconstant.
DW_OP_const2s
The single operand of the DW_OP_const2s operation provides a 2-byte signed integerconstant.
DW_OP_const4u
The single operand of the DW_OP_const4u operation provides a 4-byte unsigned integerconstant.
DW_OP_const4s
The single operand of the DW_OP_const4s operation provides a 4-byte signed integerconstant.
DW_OP_const8u
The single operand of the DW_OP_const8u operation provides an 8-byte unsigned integerconstant.
DW_OP_const8s
The single operand of the DW_OP_const8s operation provides an 8-byte signed integerconstant.
DW_OP_constu
The single operand of the DW_OP_constu operation provides an unsigned LEB128 integerconstant.
DW_OP_consts
The single operand of the DW_OP_consts operation provides a signed LEB128 integerconstant.
DW_OP_const1_type
The DW_OP_const1_type operation takes two operands.The first operand is an unsigned LEB128 integer that represents the offsetof a debugging information entry in the current compilation unit,which must be a DW_TAG_base_type entry that provides the type ofthe constant provided.The second operand is a 1-byte constant to be interpreted as a value of that type.
DW_OP_const2_type
The DW_OP_const2_type operation takes two operands.The first operand is an unsigned LEB128 integer that represents the offsetof a debugging information entry in the current compilation unit,which must be a DW_TAG_base_type entry that provides the type ofthe constant provided.The second operand is a 2-byte constant to be interpreted as a value of that type.
DW_OP_const4_type
The DW_OP_const4_type operation takes two operands.The first operand is an unsigned LEB128 integer that represents the offsetof a debugging information entry in the current compilation unit,which must be a DW_TAG_base_type entry that provides the type ofthe constant provided.The second operand is a 4-byte constant to be interpreted as a value of that type.
DW_OP_const8_type
The DW_OP_const8_type operation takes two operands.The first operand is an unsigned LEB128 integer that represents the offsetof a debugging information entry in the current compilation unit,which must be a DW_TAG_base_type entry that provides the type ofthe constant provided.The second operand is an 8-byte constant to be interpreted as a value of that type.
DW_OP_const_type
The DW_OP_const_type operation takes three operands.The first operand is an unsigned LEB128 integer that represents the offsetof a debugging information entry in the current compilation unit,which must be a DW_TAG_base_type entry that provides the type ofthe constant provided.The second operand is 1-byte unsigned integer that represents the sizen of the constant, which may not be larger than the size of the largestsupported base type of the target machine.The second operand is a block of n bytesto be interpreted as a value of the referenced type.
While the size of the constant could be inferredfrom the base type definition, it is encoded explicitly into the expressionso that the expression can be parsed easily without reference to the.debug_info section.
The following operations push a value onto the stack that is the result of adding the contents of aregister with a given signed offset.
DW_OP_fbreg
The DW_OP_fbreg operation provides a signed LEB128 offset from the address specified bythe location description in the DW_AT_frame_base attribute of the current function. (This istypically a “stack pointer” register plus or minus some offset. On more sophisticated systemsit might be a location list that adjusts the offset according to changes in the stack pointer asthe PC changes.)
DW_OP_breg0, DW_OP_breg1, ..., DW_OP_breg31
The single operand of the DW_OP_bregn operations provides a signed LEB128 offset fromthe address contained in the specified register.
DW_OP_bregx
The DW_OP_bregx operation has two operands: a register which is defined with an unsignedLEB128 number, followed by a signed LEB128 offset.
This operation pushes the address formed by adding the contents of thespecified base register and the offset.
The following operations read a value from a register and push that value onto the stack.
DW_OP_regval
The single operand of the DW_OP_regval operation provides an unsigned LEB128number, which identifies a register whose contents is to be pushed onto thestack as an integer of size equal to the address size of the target machine.
DW_OP_regval_type
The DW_OP_regval_type operation takes two parameters.The first parameter is an unsigned LEB128 number, which identifies a registerwhose contents is to be pushed onto the stack.The second parameter is an unsigned LEB128 number that represents the offsetof a debugging information entry in the current compilation unit,which must be a DW_TAG_base_type entry that provides the type ofthe value contained in the specified register.
The following operations manipulate the DWARF stack. Operations that index the stack assumethat the top of the stack (most recently added entry) has index 0.
DW_OP_dup
The DW_OP_dup operation duplicates the value at the top of the stack.
DW_OP_drop
The DW_OP_drop operation pops the value at the top of the stack.
DW_OP_pick
The single operand of the DW_OP_pick operation provides a 1-byte index. The stack entrywith the specified index (0 through 255, inclusive) is pushed on the stack.
DW_OP_over
The DW_OP_over operation duplicates the entry currently second in the stack at the top ofthe stack. This is equivalent to a DW_OP_pick operation, with index 1.
DW_OP_swap
The DW_OP_swap operation swaps the top two stack entries. The entry at the top of thestack becomes the second stack entry, and the second entry becomes the top of the stack.
DW_OP_rot
The DW_OP_rot operation rotates the first three stack entries. The entry at the top of thestack becomes the third stack entry, the second entry becomes the top of the stack, and thethird entry becomes the second entry.
DW_OP_deref
The DW_OP_deref operation pops the top stack entry and treats it as an address. The valueretrieved from that address is pushed. The size of the data retrieved from the dereferencedaddress is the size of an address on the target machine.
DW_OP_deref_size
The DW_OP_deref_size operation behaves like the DW_OP_deref operation: it pops the topstack entry and treats it as an address. The value retrieved from that address is pushed. In the DW_OP_deref_size operation, however, the size in bytes of the data retrieved from thedereferenced address is specified by the single operand. This operand is a 1-byte unsignedintegral constant whose value may not be larger than the size of an address on the targetmachine. The data retrieved is zero extended to the size of an address on the target machinebefore being pushed on the expression stack.
DW_OP_deref_type
The DW_OP_deref_type operation behaves like the DW_OP_deref_size operation: it pops the topstack entry and treats it as an address. The value retrieved from that address is pushed. In the DW_OP_deref_type operation, the size in bytes of the data retrieved from thedereferenced address is specified by the first operand. This operand is a 1-byte unsignedintegral constant whose value may not be larger than the size of the largest supported base type on the targetmachine. The second operand is an unsigned LEB128 integer that represents the offsetof a debugging information entry in the current compilation unit,which must be a DW_TAG_base_type entry that provides the type ofthe data retrieved.
DW_OP_xderef
The DW_OP_xderef operation provides an extended dereference mechanism. The entry atthe top of the stack is treated as an address. The second stack entry is treated as an “addressspace identifier” for those architectures that support multiple address spaces. The top twostack elements are popped, a data item is retrieved through an implementation-definedaddress calculation and pushed as the new stack top. The size of the data retrieved from thedereferenced address is the size of an address on the target machine.
DW_OP_xderef_size
The DW_OP_xderef_size operation behaves like the DW_OP_xderef operation: the entry atthe top of the stack is treated as an address. The second stack entry is treated as an “addressspace identifier” for those architectures that support multiple address spaces. The top twostack elements are popped, a data item is retrieved through an implementation-definedaddress calculation and pushed as the new stack top. In the DW_OP_xderef_size operation,however, the size in bytes of the data retrieved from the dereferenced address is specified bythe single operand. This operand is a 1-byte unsigned integral constant whose value may notbe larger than the size of an address on the target machine. The data retrieved is zeroextended to the size of an address on the target machine before being pushed on theexpression stack.
DW_OP_xderef_type
The DW_OP_xderef_type operation behaves like the DW_OP_xderef_size operation:it pops the top two stack entries, treats them as an address and an address space identifier,and pushes the value retrieved. In the DW_OP_xderef_type operation, the size in bytesof the data retrieved from the dereferenced address is specified by the first operand.This operand is a 1-byte unsigned integral constant whose value may not be larger thanthe size of the largest supported base type on the target machine. The second operandis an unsigned LEB128 integer that represents the offset of a debugging information entryin the current compilation unit, which must be a DW_TAG_base_type entry that providesthe type of the data retrieved.
DW_OP_push_object_address
The DW_OP_push_object_address operation pushes the address of the object currently beingevaluated as part of evaluation of a user presented expression. This object may correspond toan independent variable described by its own DIE or it may be a component of an array,structure, or class whose address has been dynamically determined by an earlier step duringuser expression evaluation.
This operator provides explicit functionality (especially for arrays involving descriptors) thatis analogous to the implicit push of the base address of a structure prior to evaluation of a DW_AT_data_member_location to access a data member of a structure. For an example, seeAppendix D.2.
DW_OP_form_tls_address
The DW_OP_form_tls_address operation pops a value from the stack, translates it into anaddress in the current thread'rsquo;s thread-local storage block, and pushes the address. If theDWARF expression containing the DW_OP_form_tls_address operation belongs to the mainexecutable'rsquo;s DWARF info, the operation uses the main executable’s thread-local storageblock; if the expression belongs to a shared library’s DWARF info, then it uses that sharedlibrary'rsquo;s thread-local storage block.
Some implementations of C and C++ support a __thread storage class. Variables with thisstorage class have distinct values and addresses in distinct threads, much as automaticvariables have distinct values and addresses in each function invocation. Typically, there is asingle block of storage containing all __thread variables declared in the main executable,and a separate block for the variables declared in each dynamically loaded library.Computing the address of the appropriate block can be complex (in some cases, the compileremits a function call to do it), and difficult to describe using ordinary DWARF locationexpressions. DW_OP_form_tls_address leaves the computation to the consumer.
DW_OP_call_frame_cfa
The DW_OP_call_frame_cfa operation pushes the value of the CFA, obtained from the CallFrame Information (see Section 6.4).
Although the value of DW_AT_frame_base can be computed using other DWARF expressionoperators, in some cases this would require an extensive location list because the values ofthe registers used in computing the CFA change during a subroutine. If the Call FrameInformation is present, then it already encodes such changes, and it is space efficient toreference that.
The following provide arithmetic and logical operations. The arithmetic operations perform“addressing arithmetic,” that is, unsigned arithmetic that wraps on an address-sized boundary.The operations do not cause an exception on overflow.
For operations that pop two values from the stack, both values must be ofthe same type, and the result will be of the same type. Explicit conversion operators(see Section 2.5.1.X) are provided for cases where type conversion is necessary.
DW_OP_abs
The DW_OP_abs operation pops the top stack entry, interprets it as a signed value andpushes its absolute value. If the absolute value can not be represented, the result is undefined.
DW_OP_and
The DW_OP_and operation pops the top two stack values, performs a bitwise and operationon the two, and pushes the result.
This operation operates only on integral values.
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.
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.
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.
DW_OP_mul
The DW_OP_mul operation pops the top two stack entries, multiplies them together, andpushes the result.
DW_OP_neg
The DW_OP_neg operation pops the top stack entry, and pushes its negation.
DW_OP_not
The DW_OP_not operation pops the top stack entry, and pushes its bitwise complement.
This operation operates only on integral values.
DW_OP_or
The DW_OP_or operation pops the top two stack entries, performs a bitwise or operation onthe two, and pushes the result.
This operation operates only on integral values.
DW_OP_plus
The DW_OP_plus operation pops the top two stack entries, adds them together, and pushesthe result.
DW_OP_plus_uconst
The DW_OP_plus_uconst operation pops the top stack entry, adds it to the unsigned LEB128constant operand and pushes the result. This operation operates only on integral values.
This operation is supplied specifically to be able to encode more field offsets in two bytesthan can be done with “DW_OP_litn DW_OP_plus”.
DW_OP_shl
The DW_OP_shl operation pops the top two stack entries, shifts the former second entry leftby the number of bits specified by the former top of the stack, and pushes the result.
This operation operates only on integral values.
DW_OP_shr
The DW_OP_shr operation pops the top two stack entries, shifts the former second entryright logically (filling with zero bits) by the number of bits specified by the former top of thestack, and pushes the result.
This operation operates only on integral values.
DW_OP_shra
The DW_OP_shra operation pops the top two stack entries, shifts the former second entryright arithmetically (divide the magnitude by 2, keep the same sign for the result) by thenumber of bits specified by the former top of the stack, and pushes the result.
This operation operates only on integral values.
DW_OP_xor
The DW_OP_xor operation pops the top two stack entries, performs the bitwise exclusive-oroperation on the two, and pushes the result.
This operation operates only on integral values.
The following operations provide simple control of the flow of a DWARF expression.
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,
compare the operands:
<former second entry> <relational operator> <former top entry>
push the constant value 1 onto the stack if the result of the operation is true or theconstant value 0 if the result of the operation is false.
The comparisons are done as signed operations. The six operators are DW_OP_le (less thanor equal to), DW_OP_ge (greater than or equal to), DW_OP_eq (equal to), DW_OP_lt (lessthan), DW_OP_gt (greater than) and DW_OP_ne (not equal to).
For these operations, both values to be compared must be ofthe same type. Explicit conversion operators (see Section 2.5.1.X) are provided forcases where type conversion is necessary.
DW_OP_skip
DW_OP_skip is an unconditional branch. Its single operand is a 2-byte signed integerconstant. The 2-byte constant is the number of bytes of the DWARF expression to skipforward or backward from the current operation, beginning after the 2-byte constant.
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-byteconstant operand is the number of bytes of the DWARF expression to skip forward orbackward from the current operation, beginning after the 2-byte constant.
DW_OP_call2, DW_OP_call4, DW_OP_call_ref
DW_OP_call2, DW_OP_call4, and DW_OP_call_ref perform subroutine calls duringevaluation of a DWARF expression. For DW_OP_call2 and DW_OP_call4, the operand isthe 2- or 4-byte unsigned offset, respectively, of a debugging information entry in the currentcompilation unit. The DW_OP_call_ref operator has a single operand. In the 32-bit DWARFformat, the operand is a 4-byte unsigned value; in the 64-bit DWARF format, it is an 8-byteunsigned value (see Section 7.4). The operand is used as the offset of a debugginginformation entry in a .debug_info section which may be contained in a shared object forexecutable other than that containing the operator. For references from one shared object orexecutable to another, the relocation must be performed by the consumer.
Operand interpretation of DW_OP_call2, DW_OP_call4 and DW_OP_call_ref is exactlylike that for DW_FORM_ref2, DW_FORM_ref4 and DW_FORM_ref_addr, respectively (seeSection 7.5.4).
These operations transfer control of DWARF expression evaluation to the DW_AT_locationattribute of the referenced DIE. If there is no such attribute, then there is no effect. Executionof the DWARF expression of a DW_AT_location attribute may add to and/or remove fromvalues on the stack. Execution returns to the point following the call when the end of theattribute is reached. Values on the stack at the time of the call may be used as parameters bythe called expression and values left on the stack by the called expression may be used asreturn values by prior agreement between the calling and called expressions.
The following operation provides for explicit type conversion.
DW_OP_convert
The DW_OP_convert operation pops the top stack entry,converts it to a different type, then pushes the result.It takes one operand, which is an unsigned LEB128 integer that represents the offsetof a debugging information entry in the current compilation unit.The referenced entry must be a DW_TAG_base_type entry that provides the typeto which the value is converted.
There is one special operation currently defined:
DW_OP_nop
The DW_OP_nop operation is a place holder. It has no effect on the location stack or any ofits values.
The stack operations defined in Section 2.5.1.3 are fairly conventional, but the followingexamples illustrate their behavior graphically.
Before Operation After 0 17 DW_OP_dup 0 17 1 29 1 17 2 1000 2 29 3 1000 0 17 DW_OP_drop 0 29 1 29 1 1000 2 1000 0 17 DW_OP_pick 2 0 1000 1 29 1 17 2 1000 2 29 3 1000 0 17 DW_OP_over 0 29 1 29 1 17 2 1000 2 29 3 1000 0 17 DW_OP_swap 0 29 1 29 1 17 2 1000 2 1000 0 17 DW_OP_rot 0 29 1 29 1 1000 2 1000 2 17Debugging information must provide consumers a way to find the location of programvariables, determine the bounds of dynamic arrays and strings, and possibly to find thebase address of a subroutine’s stack frame or the return address of a subroutine.Furthermore, to meet the needs of recent computer architectures and optimizationtechniques, debugging information must be able to describe the location of an objectwhose location changes over the object’s lifetime.
Information about the location of program objects is provided by location descriptions.Location descriptions can have either of two forms:
Normal location descriptions, which are a language independent representation ofaddressing rules of arbitrary complexity built from DWARF expressions and/or otherDWARF operations specific to describing locations. They are sufficient for describingthe location of any object as long as its lifetime is either static or the same as the lexicalblock that owns it, and it does not move throughout its lifetime.
Normal location descriptions are of two kinds:
a. Simple location descriptions, which describe the location of one contiguouspiece (usually all) of an object. Simple location descriptions may describe alocation in addressable memory, in a register, or the lack of a location (with orwithout known contents).
b. Composite location descriptions, which describe pieces of an object each ofwhich may be contained in part of a register or stored in more than one location.
Location lists, which are used to describe objects that have a limited lifetime or changetheir location throughout their lifetime. Location lists are more completely describedbelow.
The two forms location description are distinguished in a context sensitive manner. As thevalue of an attribute, a normal location description is encoded using class block and alocation list is encoded using class loclistptr (which serves as an offset into a separatelocation list table).
Note: The DWARF Version 1 concept of “location descriptions” was replaced in Version 2with this new abstraction because it is denser and more descriptive.
A normal location description is either:
A simple location description, representing an object which exists in one contiguouspiece at the given location, or
One or more simple location expressions, each of which is followed by onecomposition operator. Each simple location expression describes the location of onepiece of the object; each composition operator describes which part of the object islocated there. Each simple location expression that is a DWARF expression isevaluated independently of any others (as though on its own separate stack, if any).
In the case of locations used for structure members, the computation implicitly pushes thebase address of the immediately containing structure on the stack before evaluation of theaddressing operation.
A simple location description describes the location of one contiguous piece or all of anobject or value.
A memory location description consists of a non-empty DWARF expression (see Section2.5), whose value is the address of a piece or all of an object or other entity in memory.
Of the several kinds of normal location description, only the memory location description(which involves evaluation of a DWARF expression) makes use of the DWARF expressionstack.
A register location description consists of a register name operation, appearing alone as asingle opcode. It represents a piece or all of an object located in a given register.
The following DWARF operations can be used to name a register.
Note that the register number represents a DWARF specific mapping of numbers onto theactual registers of a given architecture. The mapping should be chosen to gain optimaldensity and should be shared by all users of a given architecture. It is recommended thatthis mapping be defined by the ABI authoring committee for each architecture.
DW_OP_reg0, DW_OP_reg1, ..., DW_OP_reg31
The DW_OP_regn operations encode the names of up to 32 registers, numbered from 0through 31, inclusive. The object addressed is in register n.
DW_OP_regx
The DW_OP_regx operation has a single unsigned LEB128 literal operand thatencodes the name of a register.
An implicit location description consists of an implicit value operation, appearing alone asa single opcode. It represents a piece or all of an object which has no actual location butwhose contents is nonetheless known.
An implicit location description represents all or a piece of an objectthat has no actual location but whose contents is nonetheless known or can be calculatedvia a DWARF expression.
The following DWARF operations can be used to specify an implicit value.
DW_OP_value
The DW_OP_value operation marks the value on the top of the stack asthe actual value to be returned rather than the location of the value.This operation may be used only when there is a single value on the stack,and may not be followed by any other operations as part of a simplelocation description. It may, however, be used as part of a compositelocation description.
DW_OP_implicit_value
The DW_OP_implicit_value operation has two operands: an unsigned LEB128 length,followed by a block representing the value in the memory representation of the targetmachine. The length operand gives the length in bytes of the block that follows.
This operation should be used only in locations lists for ranges where the value of anobject does not exist in memory or a register, but whose value is a known constant.When used as a simple location description, it must be used alone;it may not be combined with other operations except as part of a composite locationdescription.
A read-only location description consists of a memory or registerlocation description, followed by a read-only operation.It represents a piece or all of an object that has a location but should notbe modified (for example, because another variable shares the same location).
The following DWARF operation can be used to specify a read-only location.
DW_OP_readonly
The DW_OP_readonly operation marks the value on thetop of the stack as a read-only location.This operation may be used only when there is a single value on the stack,and may not be followed by any other operations as part of a simplelocation description. It may, however, be used as part of a compositelocation description.
An empty location description consists of a DWARF expression containing no operations.It represents a piece or all of an object that is present in the source code but not in theobject code (perhaps due to optimization).
A composite location description describes an object or value which may be contained inpart of a register or stored in more than one piece. Each piece is described by a compositionoperation, which does not compute a value nor store any result on the DWARF stack.There may be one or more composition operators in a single DWARF composition locationdescription. A series of such operations describes the parts of a value in memory addressorder.
Each composition operation is immediately preceded by a simple location descriptionwhich describes the location where part of the resultant value is contained.
A composite location description may consist of an arbitrary mixture of piecesdescribed by memory, register, implicit, read-only, and empty location descriptions.
DW_OP_piece
The DW_OP_piece operation takes a single operand, which is an unsigned LEB128number. The number describes the size in bytes of the piece of the object referenced bythe preceding simple location description. If the piece is located in a register, but doesnot occupy the entire register, the placement of the piece within that register is definedby the ABI.
Many compilers store a single variable in sets of registers, or store a variable partiallyin memory and partially in registers. DW_OP_piece provides a way of describing howlarge a part of a variable a particular DWARF expression refers to.
DW_OP_bit_piece
The DW_OP_bit_piece operation takes two operands. The first is an unsigned LEB128number that gives the size in bits of the piece. The second is an unsigned LEB128number that gives the offset in bits from the location defined by the preceding DWARFlocation description.
Interpretation of the offset depends on the kind of location description. If the locationdescription is empty, the offset doesn’t matter and the DW_OP_bit_piece operatordescribes a piece consisting of the given number of bits whose values are undefined. Ifthe location is a register, the offset is from the least significant bit end of the register. Ifthe location is a memory address, the DW_OP_bit_piece operator describes a sequenceof bits relative to the location whose address is on the top of the DWARF stack usingthe bit numbering and direction conventions that are appropriate to the current languageon the target system.
DW_OP_bit_piece is used instead of DW_OP_piece when the piece to be assembled into avalue or assigned to is not byte-sized or is not at the start of a register or addressable unitof memory.
The addressing expression represented by a memory location description, if evaluated,generates the runtime address of the value of a symbol.
Here are some examples of how DWARF operations are used to form locationdescriptions:
DW_OP_reg3
The value is in register 3.
DW_OP_regx 54
The value is in register 54.
DW_OP_addr 0x80d0045c
The value of a static variable is at machine address 0x80d0045c.
DW_OP_breg11 44
Add 44 to the value in register 11 to get the address of an automatic variable instance.
DW_OP_fbreg -50
Given an
DW_AT_frame_basevalue of “DW_OP_breg31 64,” this example computes the address of a local variable that is -50 bytes from a logical frame pointer that is computed by adding 64 to the current stack pointer (register 31).
DW_OP_bregx 54 32 DW_OP_deref
A call-by-reference parameter whose address is in the word 32 bytes from where register 54 points.
DW_OP_plus_uconst 4
A structure member is four bytes from the start of the structure instance. The base address is assumed to be already on the stack.
DW_OP_reg3 DW_OP_piece 4 DW_OP_reg10 DW_OP_piece 2
A variable whose first four bytes reside in register 3 and whose next two bytes reside in register 10.
DW_OP_reg0 DW_OP_piece 4 DW_OP_piece 4 DW_OP_fbreg -12 DW_OP_piece 4
A twelve byte value whose first four bytes reside in register zero, whose middle four bytes are unavailable (perhaps due to optimization), and whose last four bytes are in memory, 12 bytes before the frame base.
DW_OP_reg3 DW_OP_readonly
A variable whose value can be found in register 3, but may be shared by one or more other variables.
DW_OP_regval 12 DW_OP_const1u 4 DW_OP_div DW_OP_value
A variable whose value does not exist in memory or any register, but whose value can be recomputed by dividing the value in register 12 by 4 (possibly an induction variable).
DW_OP_reg0 DW_OP_piece 4 DW_OP_piece 4 DW_OP_fbreg -32 DW_OP_piece 16
A 24-byte structure whose first four bytes reside in register zero; whose next four bytes are unavailable (perhaps due to structure padding); and whose next 16 bytes are in memory, 32 bytes before the frame base.
DW_OP_reg0 DW_OP_piece 4 DW_OP_piece 4 DW_OP_regval_type 64 <n> DW_OP_const1u 2 DW_OP_convert <n>
DW_OP_mul DW_OP_piece 8 DW_OP_fbreg -24 DW_OP_piece 8
As above, except that bytes 8-15 contain a floating-point value computed by multiplying the contents of register 64 by 2.0. The offset
<n>is a reference to aDW_TAG_base_typedebugging information entry in the current compilation unit that describes an 8-byte floating-point base type. (For the purposes of this example, assume that register 64 is a floating-point register.)
DW_OP_reg0 DW_OP_piece 4 DW_OP_piece 4 DW_OP_regval_type 64 <n> DW_OP_const1u 2 DW_OP_convert <n>
DW_OP_mul DW_OP_piece 8 DW_OP_reg 65 DW_OP_readonly DW_OP_piece 8
As above, except that bytes 16-23 are located in register 65, but may not be modified because that register is shared by at least one other variable. (For the purposes of this example, assume that register 65 is a floating-point register.)
Location lists are used in place of location descriptions whenever the object whose locationis being described can change location during its lifetime. Location lists are contained in aseparate object file section called .debug_loc. A location list is indicated by a locationattribute whose value is represented as an offset from the beginning of the .debug_locsection to the first byte of the list for the object in question.
Each entry in a location list is either a location list entry, a base address selection entry, oran end of list entry.
A location list entry consists of:
A beginning address offset. This address offset has the size of an address and is relativeto the applicable base address of the compilation unit referencing this location list. Itmarks the beginning of the address range over which the normal location description isvalid.
An ending address offset. This address offset again has the size of an address and isrelative to the applicable base address of the compilation unit referencing this locationlist. It marks the first address past the end of the address range over which the normallocation description is valid. The ending address must be greater than or equal to thebeginning address.
A location list entry (but not a base address selection or end of list entry) whosebeginning and ending addresses are equal has no effect because the size of the rangecovered by such an entry is zero.
A normal location description describing the location of the object over the rangespecified by the beginning and ending addresses.
The applicable base address of a location list entry is determined by the closest precedingbase address selection entry (see below) in the same location list. If there is no suchselection entry, then the applicable base address defaults to the base address of thecompilation unit (see Section ).
In the case of a compilation unit where all of the machine code is contained in a singlecontiguous section, no base address selection entry is needed.
Address ranges may overlap. When they do, they describe a situation in which an objectexists simultaneously in more than one place. If all of the address ranges in a given locationlist do not collectively cover the entire range over which the object in question is defined, itis assumed that the object is not available for the portion of the range that is not covered.
A base address selection entry consists of:
The value of the largest representable address offset (for example, 0xffffffff when thesize of an address is 32 bits).
An address, which defines the appropriate base address for use in interpreting thebeginning and ending address offsets of subsequent entries of the location list.
A base address selection entry affects only the list in which it is contained.
The end of any given location list is marked by an end of list entry, which consists of a 0for the beginning address offset and a 0 for the ending address offset. A location listcontaining only an end of list entry describes an object that exists in the source code but notin the executable program.
Neither a base address selection entry nor an end of list entry includes a locationdescription.
A base address selection entry and an end of list entry for a location list are identical to abase address selection entry and end of list entry, respectively, for a range list (see Section XX)in interpretation and representation.