Bring up to date with approved issues as of April 2014.
[dwarf-doc.git] / dwarf5 / latexdoc / generaldescription.tex
index 0f40da8..fdc4a86 100644 (file)
@@ -35,6 +35,8 @@ described in Chapters 3, 4 and 5.
 \DWTAGarraytype,
 \DWTAGatomictype,
 \DWTAGbasetype,
+\DWTAGcallsite,
+\DWTAGcallsiteparameter,
 \DWTAGcatchblock,
 \DWTAGclasstype,
 \DWTAGcoarraytype,
@@ -214,15 +216,90 @@ to one of the classes shown in Table \refersec{tab:classesofattributevalue}.
 \DWATbytestrideTARG{} 
 &\livelinki{chap:DWATbytestridearrayelementstrideofarraytype}{Array element stride (of array type)}{array element stride (of array type)} \\
 &\livelinki{chap:DWATbytestridesubrangestridedimensionofarraytype}{Subrange stride (dimension of array type)}{subrange stride (dimension of array type)} \\
-&\livelinki{chap:DWATbytestrideenumerationstridedimensionofarraytype}{Enumeration stride (dimension of array type)}{enumeration stride (dimension of array type)} \\
+&\livelinki{chap:DWATbytestrideenumerationstridedimensionofarraytype}
+           {Enumeration stride (dimension of array type)}
+           {enumeration stride (dimension of array type)} \\
+\DWATcallallcallsTARG{}
+&\livelinki{chap:DWATcallallcallsofasubprogram}
+           {All tail and normal calls in a subprogram are described by call site entries}
+           {all tail and normal calls in a subprogram are described by call site entries}
+           \index{call site!summary!all tail and normal calls are described} \\
+\DWATcallallsourcecallsTARG{}
+&\livelinki{chap:DWATcallallaourcecallsofa subprogram}
+           {All tail, normal and inlined calls in a subprogram are described by call site and inlined subprogram entries}
+           {all tail calls in a subprogram are described by call site and inlined subprogram entries}
+           \index{call site!summary!all tail, normal and inlined calls are described} \\
+\DWATcallalltailcallsTARG{}
+&\livelinki{chap:DWATcallalltailcallsofasubprogram}
+           {All tail calls in a subprogram are described by call site entries}
+           {all tail calls in a subprogram are described by call site entries}
+           \index{call site!summary!all tail calls are described} \\
 \DWATcallcolumnTARG{} 
-&\livelinki{chap:DWATcallcolumncolumnpositionofinlinedsubroutinecall}{Column position of inlined subroutine call}{column position of inlined subroutine call}\\
+&\livelinki{chap:DWATcallcolumncolumnpositionofinlinedsubroutinecall}
+           {Column position of inlined subroutine call}
+           {column position of inlined subroutine call} \\
+\DWATcalldatalocationTARG{}
+&\livelinki{chap:DWATcalldatalocationofcallsite}
+           {Address of the value pointed to by an argument passed in a call}
+           {address of the value pointed to by an argument passed in a call}
+           \index{call site!address of the value pointed to by an argument} \\
+\DWATcalldatavalueTARG{}
+&\livelinki{chap:DWATcalldatavalueofcallsite}
+           {Value pointed to by an argument passed in a call}
+           {value pointed to by an argument passed in a call}
+           \index{call site!value pointed to by an argument} \\
 \DWATcallfileTARG
-&\livelinki{chap:DWATcallfilefilecontaininginlinedsubroutinecall}{File containing inlined subroutine call}{file containing inlined subroutine call} \\
+&\livelinki{chap:DWATcallfilefilecontaininginlinedsubroutinecall}
+           {File containing inlined subroutine call}
+           {file containing inlined subroutine call} \\
 \DWATcalllineTARG{} 
-&\livelinki{chap:DWATcalllinelinenumberofinlinedsubroutinecall}{Line number of inlined subroutine call}{line number of inlined subroutine call} \\
+&\livelinki{chap:DWATcalllinelinenumberofinlinedsubroutinecall}
+           {Line number of inlined subroutine call}
+           {line number of inlined subroutine call} \\
 \DWATcallingconventionTARG{} 
-&\livelinki{chap:DWATcallingconventionsubprogramcallingconvention}{Subprogram calling convention}{subprogram calling convention} \\
+&\livelinki{chap:DWATcallingconventionsubprogramcallingconvention}
+           {Subprogram calling convention}
+           {subprogram calling convention} \\
+\DWATcalloriginTARG{}
+&\livelinki{chap:DWATcalloriginofcallsite}
+           {Subprogram called in a call}
+           {subprogram called in a call}
+           \index{call site!subprogram called} \\
+\DWATcallparameterTARG{}
+&\livelinki{chap:DWATcallparameterofcallsite}
+           {Parameter entry in a call}
+           {parameter entry in a call}
+           \index{call site!parameter entry} \\
+\DWATcallpcTARG{}
+&\livelinki{chap:DWATcallpcofcallsite}
+           {Address of the call instruction in a call}
+           {address of the call instruction in a call}
+           \index{call site!address of the call instruction} \\
+\DWATcallreturnpcTARG{}
+&\livelinki{chap:DWATcallreturnpcofcallsite}
+           {Return address from a call}
+           {return address from a call}
+           \index{call site!return address} \\
+\DWATcalltailcallTARG{}
+&\livelinki{chap:DWATcalltailcallofcallsite}
+           {Call is a tail call}
+           {call is a tail call}
+           \index{call site!tail call} \\
+\DWATcalltargetTARG{}
+&\livelinki{chap:DWATcalltargetofcallsite}
+           {Address of called routine in a call}
+           {address of called routine in a call}
+           \index{call site!address of called routine} \\
+\DWATcalltargetclobberedTARG{}
+&\livelinki{chap:DWATcalltargetclobberedofcallsite}
+           {Address of called routine, which may be clobbered, in a call}
+           {address of called routine, which may be clobbered, in a call}
+           \index{call site!address of called routine, which may be clobbered} \\
+\DWATcallvalueTARG{}
+&\livelinki{chap:DWATcallvalueofcallsite}
+           {Argument value passed in a call}
+           {argument value passed in a call}
+           \index{call site!argument value passed} \\
 \DWATcommonreferenceTARG
 &\livelinki{chap:commonreferencecommonblockusage}{Common block usage}{common block usage} \\
 \DWATcompdirTARG
@@ -723,24 +800,25 @@ The single operand of a \DWOPconstnsNAME{} operation provides a 1,
 
 \itembfnl{\DWOPconstuTARG}
 The single operand of the \DWOPconstuNAME{} operation provides
-an unsigned LEB128 integer constant.
+an unsigned LEB128\addtoindexx{LEB128!unsigned} integer constant.
 
 \itembfnl{\DWOPconstsTARG}
 The single operand of the \DWOPconstsNAME{} operation provides
-a signed LEB128 integer constant.
+a signed LEB128\addtoindexx{LEB128!unsigned} integer constant.
 
 \needlines{4}
 \itembfnl{\DWOPaddrxTARG}
 The \DWOPaddrxNAME{} operation has a single operand that
-encodes an unsigned LEB128 value, which is a zero-based
-index into the \dotdebugaddr{} section, where a machine
-address is stored.
+encodes an unsigned LEB128\addtoindexx{LEB128!unsigned} value, 
+which is a zero-based index into the \dotdebugaddr{} section, 
+where a machine address is stored.
 This index is relative to the value of the 
 \DWATaddrbase{} attribute of the associated compilation unit.
 
 \itembfnl{\DWOPconstxTARG}
 The \DWOPconstxNAME{} operation has a single operand that
-encodes an unsigned LEB128 value, which is a zero-based
+encodes an unsigned LEB128\addtoindexx{LEB128!unsigned} value, 
+which is a zero-based
 index into the \dotdebugaddr{} section, where a constant, the
 size of a machine address, is stored.
 This index is relative to the value of the 
@@ -762,7 +840,8 @@ the result of adding the contents of a register to a given
 signed offset.
 \begin{enumerate}[1. ]
 \itembfnl{\DWOPfbregTARG}
-The \DWOPfbregTARG{} operation provides a signed LEB128 offset
+The \DWOPfbregTARG{} operation provides a 
+signed LEB128\addtoindexx{LEB128!signed} offset
 from the address specified by the location description in the
 \DWATframebase{} attribute of the current function. (This
 is typically a \doublequote{stack pointer} register plus or minus
@@ -773,13 +852,13 @@ in the stack pointer as the PC changes.)
 \itembfnl{\DWOPbregzeroTARG, \DWOPbregoneTARG, \dots, \DWOPbregthirtyoneTARG}
 The single operand of the \DWOPbregnTARG{} 
 operations provides
-a signed LEB128 offset from
+a signed LEB128\addtoindexx{LEB128!signed} offset from
 the specified register.
 
 \itembfnl{\DWOPbregxTARG{} }
 The \DWOPbregxINDX{} operation has two operands: a register
-which is specified by an unsigned LEB128 number, followed by
-a signed LEB128 offset.
+which is specified by an unsigned LEB128\addtoindexx{LEB128!unsigned}
+number, followed by a signed LEB128\addtoindexx{LEB128!signed} offset.
 
 \end{enumerate}
 
@@ -1012,8 +1091,8 @@ adds them together, and pushes the result.
 \needlines{6}
 \itembfnl{\DWOPplusuconstTARG}
 The \DWOPplusuconstTARG{} operation pops the top stack entry,
-adds it to the unsigned LEB128 constant operand and pushes
-the result.
+adds it to the unsigned LEB128\addtoindexx{LEB128!unsigned}
+constant operand and pushes the result.
 
 \textit{This operation is supplied specifically to be
 able to encode more field offsets in two bytes than can be
@@ -1144,11 +1223,44 @@ by prior agreement between the calling and called expressions.
 \subsubsection{Special Operations}
 There 
 \addtoindexx{DWARF expression!special operations}
-is one special operation currently defined:
+are these special operations currently defined:
 \begin{enumerate}[1. ]
-\itembfnl{\DWOPnopTARG}
+\itembfnl{\DWOPnopNAME}
 The \DWOPnopTARG{} operation is a place holder. It has no effect
 on the location stack or any of its values.
+
+\itembfnl{\DWOPentryvalueNAME}
+The \DWOPentryvalueTARG{} operation pushes a value that had a known location
+upon entering the current subprogram.  It uses two operands: an 
+unsigned LEB128\addtoindexx{LEB128!unsigned} length, followed by 
+a block containing a DWARF expression or
+a simple register location description.  The length gives the length
+in bytes of the block.  If the block contains a register location
+description, \DWOPentryvalueNAME{} pushes the value that register had upon
+entering the current subprogram.  If the block contains a DWARF expression,
+the DWARF expression is evaluated as if it has been evaluated upon entering
+the current subprogram.  The DWARF expression should not assume any values
+being present on the DWARF stack initially and should result in exactly one
+value being pushed on the DWARF stack when completed.  That value is the value
+being pushed by the \DWOPentryvalueNAME{} operation.  
+
+\DWOPpushobjectaddress{} is not meaningful inside of this DWARF operation.
+
+\textit{The \DWOPentryvalueNAME{} operation can be used by consumers if they are able
+to find the call site in the caller function, unwind to it and the corresponding
+\DWTAGcallsiteparameter{} entry has \DWATcallvalue{} or
+\DWATcalldatavalue{} attributes that can be evaluated to find out the
+value a function parameter had on the first instruction in the function.
+Or non-interactive consumers which know what variables will need to be
+inspected ahead of running the debugged program could put breakpoint
+on the first instruction in functions where there is no other way to find
+some variable's value, but evaluating \DWOPentryvalueNAME{} operation.  The
+consumer can collect there the value of registers or memory referenced in
+\DWOPentryvalueNAME{} operations, then continue to breakpoints where the values
+of variables or parameters need to be inspected and use there the remembered
+register or memory values during \DWOPentryvalueNAME{} evaluation.
+}
+
 \end{enumerate}
 
 \subsection{Example Stack Operations}
@@ -1347,7 +1459,8 @@ addressed is in register \textit{n}.
 
 \needlines{4}
 \itembfnl{\DWOPregxTARG}
-The \DWOPregxTARG{} operation has a single unsigned LEB128 literal
+The \DWOPregxTARG{} operation has a single 
+unsigned LEB128\addtoindexx{LEB128!unsigned} literal
 operand that encodes the name of a register.  
 
 \end{enumerate}
@@ -1376,7 +1489,8 @@ or is computed from other locations and values in the program.
 \itembfnl{\DWOPimplicitvalueTARG}
 The \DWOPimplicitvalueTARG{} 
 operation specifies an immediate value
-using two operands: an unsigned LEB128 length, followed by
+using two operands: an unsigned LEB128\addtoindexx{LEB128!unsigned}
+length, followed by
 %FIXME: should this block be a reference? To what?
 a \nolink{block} representing the value in the memory representation
 of the target machine. The length operand gives the length
@@ -1411,7 +1525,8 @@ The first operand is a 4-byte unsigned value in the 32-bit
 DWARF format, or an 8-byte unsigned value in the 64-bit 
 DWARF format (see Section 
 \refersec{datarep:32bitand64bitdwarfformats}).
-The second operand is a \addtoindex{signed LEB128} number.
+The second operand is a 
+signed LEB128\addtoindexx{LEB128!signed} number.
 
 The first operand is used as the offset of a debugging
 information entry in a \dotdebuginfo{} section, which may be
@@ -1473,7 +1588,8 @@ of the resultant value is contained.
 \itembfnl{\DWOPpieceTARG}
 The \DWOPpieceTARG{} operation takes a 
 single operand, which is an
-unsigned LEB128 number.  The number describes the size in bytes
+unsigned LEB128\addtoindexx{LEB128!unsigned} number.  
+The number describes the size in bytes
 of the piece of the object referenced by the preceding simple
 location description. If the piece is located in a register,
 but does not occupy the entire register, the placement of
@@ -1488,8 +1604,10 @@ refers to. }
 \itembfnl{\DWOPbitpieceTARG}
 The \DWOPbitpieceTARG{} 
 operation takes two operands. The first
-is an unsigned LEB128 number that gives the size in bits
-of the piece. The second is an unsigned LEB128 number that
+is an unsigned LEB128\addtoindexx{LEB128!unsigned} 
+number that gives the size in bits
+of the piece. The second is an 
+unsigned LEB128\addtoindexx{LEB128!unsigned} number that
 gives the offset in bits from the location defined by the
 preceding DWARF location description.  
 
@@ -1538,6 +1656,7 @@ The value of a static variable is at machine address 0x80d0045c.
 Add 44 to the value in register 11 to get the address of an automatic
 variable instance.
 
+\needlines{4}
 \descriptionitemnl{\DWOPfbreg{} -50}
 Given a \DWATframebase{} value of
 \doublequote{\DWOPbregthirtyone{} 64,} this example
@@ -1549,6 +1668,7 @@ stack pointer (register 31).
 A call-by-reference parameter whose address is in the word 32 bytes
 from where register 54 points.
 
+\needlines{4}
 \descriptionitemnl{\DWOPplusuconst{} 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.
@@ -1558,7 +1678,7 @@ A variable whose first four bytes reside in register 3 and whose next
 two bytes reside in register 10.
 
 \descriptionitemnl{\DWOPregzero{} \DWOPpiece{} 4 \DWOPpiece{} 4 \DWOPfbreg{} -12 \DWOPpiece{} 4}
-A twelve byte value whose first four bytes reside in register zero,
+\vspace{-2\parsep}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.
@@ -1567,14 +1687,36 @@ base.
 Add the contents of r1 and r2 to compute a value. This value is the
 \doublequote{contents} of an otherwise anonymous location.
 
-\needlines{6}
-\descriptionitemnl{\DWOPlitone{} \DWOPstackvalue{} \DWOPpiece{} 4 }
-\vspace{-0.1\parsep}
-\descriptionitemnl{\DWOPbregthree 0 \DWOPbregfour 0 \DWOPplus{} \DWOPstackvalue{} \DWOPpiece{} 4}
+
+\descriptionitemnl{\DWOPlitone{} \DWOPstackvalue{} \DWOPpiece{} 4 \DWOPbregthree{} 0 \DWOPbregfour{} 0}
+\vspace{-2\parsep}\descriptionitemnl{
+\hspace{0.5cm}\DWOPplus{} \DWOPstackvalue{} \DWOPpiece{} 4 \DWOPpiece{} 4}
 The object value is found in an anonymous (virtual) location whose
 value consists of two parts, given in memory address order: the 4 byte
 value 1 followed by the four byte value computed from the sum of the
 contents of r3 and r4.
+
+\descriptionitemnl{\DWOPentryvalue{} 1 \DWOPregone{} \DWOPstackvalue }
+The value register 1 had upon entering the current subprogram.
+
+\descriptionitemnl{\DWOPentryvalue{} 2 \DWOPbregone{} 0 \DWOPstackvalue }
+The value register 1 had upon entering the current subprogram (same as the previous example).
+%Both of these location descriptions evaluate to the value register 1 had upon
+%entering the current subprogram.
+
+%FIXME: The following gets an undefined control sequence error for reasons unknown... 
+%\descriptionitemnl{\DWOPentryvalue{} 1 \DWOPregthirtyone{} \DWOPregone{} \DWOPadd{} \DWOPstackvalue }
+%The value register 31 had upon entering the current subprogram
+%plus the value register 1 currently has.
+
+\descriptionitemnl{\DWOPentryvalue{} 3 \DWOPbregfour{} 16 \DWOPderef{} \DWOPstackvalue }
+%FIXME: similar undefined as just above
+%\descriptionitemnl{\DWOPentryvalue{} 6 \DWOPentryvalue{} 1 \DWOPregfour{} \DWOPplusuconst{} 16 \DWOPderef{} \DWOPstackvalue }
+%These two location expressions do the same thing, p
+Push the value of the
+memory location with the size of an address pointed to by the value of
+register 4 upon entering the current subprogram and add 16.
+
 \end{description}
 
 
@@ -1764,7 +1906,8 @@ This entry indicates the end of a location list, and
 contains no further data.
 
 \itembfnl{\DWLLEbaseaddressselectionentryTARG}
-This entry contains an unsigned LEB128 value immediately
+This entry contains an 
+unsigned LEB128\addtoindexx{LEB128!unsigned} value immediately
 following the type code. This value is the index of an
 address in the \dotdebugaddr{} section, which is then used as
 the base address when interpreting offsets in subsequent
@@ -1773,8 +1916,8 @@ This index is relative to the value of the
 \DWATaddrbase{} attribute of the associated compilation unit.
 
 \itembfnl{\DWLLEstartendentryTARG}
-This entry contains two unsigned LEB128 values
-immediately following the type code. These values are the
+This entry contains two unsigned LEB128\addtoindexx{LEB128!unsigned}
+values immediately following the type code. These values are the
 indices of two addresses in the \dotdebugaddr{} section.
 These indices are relative to the value of the 
 \DWATaddrbase{} attribute of the associated compilation unit.
@@ -1786,7 +1929,8 @@ compilation unit base address. A single location
 description follows the fields that define the address range.
 
 \itembfnl{\DWLLEstartlengthentryTARG}
-This entry contains one unsigned LEB128 value and a 4-byte
+This entry contains one unsigned LEB128\addtoindexx{LEB128!unsigned}
+value and a 4-byte
 unsigned value immediately following the type code. The
 first value is the index of an address in the \dotdebugaddr{}
 section, which marks the beginning of the address range