Bring up to date with approved issues as of April 2014.
[dwarf-doc.git] / dwarf5 / latexdoc / programscope.tex
index 92398ec..cd55274 100644 (file)
@@ -140,34 +140,38 @@ in Table \refersec{tab:languagenames}.
 \begin{tabular}{l|l}
 \hline
 Language name & Meaning\\ \hline
-\DWLANGAdaeightythreeTARG{} \dag & ISO \addtoindex{Ada}:1983 \addtoindexx{Ada} \\
-\DWLANGAdaninetyfiveTARG{} \dag & ISO Ada:1995 \addtoindexx{Ada} \\
-\DWLANGCTARG & Non-standardized C, such as K\&R \\
-\DWLANGCeightynineTARG & ISO C:1989 \\
-\DWLANGCninetynineTARG & ISO \addtoindex{C}:1999 \\
-\DWLANGCplusplusTARG & ISO \addtoindex{C++}:1998 \\
-\DWLANGCpluspluszerothreeTARG & ISO \addtoindex{C++}:2003 \\
-\DWLANGCpluspluselevenTARG & ISO \addtoindex{C++}:2011 \\
-\DWLANGCobolseventyfourTARG & ISO \addtoindex{COBOL}:1974 \\
-\DWLANGCoboleightyfiveTARG & ISO \addtoindex{COBOL}:1985 \\
+\addtoindexx{ISO-defined language names}
+\DWLANGAdaeightythreeTARG{} \dag & ISO Ada:1983 \addtoindexx{Ada:1983 (ISO)} \\
+\DWLANGAdaninetyfiveTARG{}  \dag & ISO Ada:1995 \addtoindexx{Ada:1995 (ISO)} \\
+\DWLANGCTARG & Non-standardized C, such as K\&R \addtoindexx{C!non-standard}\\
+\DWLANGCeightynineTARG & ISO C:1989 \addtoindexx{C:1989 (ISO)} \\
+\DWLANGCninetynineTARG & ISO C:1999 \addtoindexx{C:1999 (ISO)} \\
+\DWLANGCelevenTARG     & ISO C:2011 \addtoindexx{C:2011 (ISO)} \\
+\DWLANGCplusplusTARG          & ISO C++:1998 \addtoindexx{C++:1998 (ISO)} \\
+\DWLANGCpluspluszerothreeTARG & ISO C++:2003 \addtoindexx{C++:2003 (ISO)} \\
+\DWLANGCpluspluselevenTARG    & ISO C++:2011 \addtoindexx{C++:2011 (ISO)} \\
+\DWLANGCobolseventyfourTARG & ISO COBOL:1974 \addtoindexx{COBOL:1974 (ISO)} \\
+\DWLANGCoboleightyfiveTARG  & ISO COBOL:1985 \addtoindexx{COBOL:1985 (ISO)} \\
 \DWLANGDTARG{} \dag & D \addtoindexx{D language} \\
-\DWLANGFortranseventysevenTARG &ISO \addtoindex{FORTRAN} 77\\
-\DWLANGFortranninetyTARG & ISO \addtoindex{Fortran 90}\\
-\DWLANGFortranninetyfiveTARG & ISO \addtoindex{Fortran 95}\\
-\DWLANGGoTARG{} \dag & \addtoindex{Go}\\
-\DWLANGHaskellTARG{} \dag & \addtoindex{Haskell}\\
+\DWLANGFortranseventysevenTARG & ISO FORTRAN:1977 \addtoindexx{FORTRAN:1977 (ISO)} \\
+\DWLANGFortranninetyTARG       & ISO Fortran:1990 \addtoindexx{Fortran:1990 (ISO)} \\
+\DWLANGFortranninetyfiveTARG   & ISO Fortran:1995 \addtoindexx{Fortran:1995 (ISO)} \\
+\DWLANGGoTARG{} \dag & \addtoindex{Go} \\
+\DWLANGHaskellTARG{} \dag & \addtoindex{Haskell} \\
 \DWLANGJavaTARG{} & \addtoindex{Java}\\
-\DWLANGModulatwoTARG & ISO Modula\dash 2:1996 \addtoindexx{Modula-2}\\
-\DWLANGModulathreeTARG & \addtoindex{Modula-3}\\
-\DWLANGObjCTARG{} & \addtoindex{Objective C}\\
-\DWLANGObjCplusplusTARG{} & \addtoindex{Objective C++}\\
-\DWLANGOCamlTARG{} \dag & \addtoindex{OCaml}\index{Objective Caml|see{OCaml}}\\
-\DWLANGOpenCLTARG{} \dag & \addtoindex{OpenCL}\\
-\DWLANGPascaleightythreeTARG & ISO \addtoindex{Pascal}:1983\\
-\DWLANGPLITARG{} \dag & ANSI \addtoindex{PL/I}:1976\\
-\DWLANGPythonTARG{} \dag & \addtoindex{Python}\\
+\DWLANGModulatwoTARG   & ISO Modula\dash 2:1996 \addtoindexx{Modula-2:1996 (ISO)} \\
+\DWLANGModulathreeTARG & \addtoindex{Modula-3} \\
+\DWLANGObjCTARG{}         & \addtoindex{Objective C} \\
+\DWLANGObjCplusplusTARG{} & \addtoindex{Objective C++} \\
+\DWLANGOCamlTARG{} \dag  & \addtoindex{OCaml}\index{Objective Caml|see{OCaml}} \\
+\DWLANGOpenCLTARG{} \dag & \addtoindex{OpenCL} \\
+\DWLANGPascaleightythreeTARG & ISO Pascal:1983 \addtoindexx{Pascal:1983 (ISO)} \\
+\DWLANGPLITARG{} \dag & ANSI PL/I:1976 \addtoindexx{PL/I:1976 (ANSI)} \\
+\DWLANGPythonTARG{} \dag & \addtoindex{Python} \\
 \DWLANGRustTARG{} \dag & \addtoindex{Rust} \\
-\DWLANGUPCTARG{} & \addtoindex{Unified Parallel C}\addtoindexx{UPC}\\ \hline
+\DWLANGUPCTARG{} & UPC (Unified Parallel C) \addtoindexx{UPC}  
+                         \index{Unified Parallel C|see{UPC}} \\ 
+\hline
 \dag \ \ \textit{Support for these languages is limited.}& \\
 \end{tabular}
 \end{table}
@@ -1096,7 +1100,37 @@ The attribute indicates whether the subroutine
 or entry point was declared with the \doublequote{recursive} keyword
 or property.
 
-
+\subsubsection{Call Site-Related Attributes}
+A subroutine entry may have \DWATcallalltailcalls, \DWATcallallcalls{} 
+and/or \DWATcallallsourcecalls{} attributes, each of which is a 
+\livelink{chap:classflag}{flag}.
+These flags indicate the completeness of the call site information 
+within the subprogram.
+
+The \DWATcallalltailcalls{} attribute indicates that every tail call 
+that occurs in the code for the subprogram is described by a 
+\DWTAGcallsite{} entry. 
+(There may or may not be other non-tail calls to some of the same 
+target subprograms.)
+
+The \DWATcallallcalls{} attribute indicates that every non-inlined call
+(either a tail call or a normal call) that occurs in the code for the subprogram
+is described by a \DWTAGcallsite{} entry.
+
+The \DWATcallallsourcecalls{} attribute indicates that every call that occurs in the
+code for the subprogram, including every call inlined into it, is described by either a 
+\DWTAGcallsite{} entry or a \DWTAGinlinedsubroutine{} entry; further, any call
+that is optimized out is nonetheless also described using a \DWTAGcallsite{} entry 
+that has neither a \DWATcallpc{} nor \DWATcallreturnpc{} attribute.
+
+\textit{The \DWATcallallsourcecalls{} attribute is intended for debugging 
+information format consumers that analyse call graphs.}
+
+If the value of the \DWATcallallsourcecalls{} attribute is true then the values of the
+\DWATcallallcalls{} and \DWATcallallcalls{} attributes are necessarily also true, and 
+those attributes need not be present. Similarly, if the value of the 
+\DWATcallallcalls{} attribute is true then the value of the \DWATcallalltailcalls{} 
+attribute is also true and the latter attribute need not be present.
 
 \subsection{Subroutine and Entry Point Return Types}
 \label{chap:subroutineandentrypointreturntypes}
@@ -1387,6 +1421,7 @@ artificially by the compiler for this instantiation.
 
 \needlines{8}
 \subsection{Inlinable and Inlined Subroutines}
+\label{chap:inlinedsubroutines}
 A declaration or a definition of an inlinable subroutine
 is represented by a debugging information entry with the
 tag 
@@ -1901,6 +1936,170 @@ hide the compiler generated subprogram from the user. }
 to repeatedly step until control arrives in a new subroutine
 which can be assumed to be the target subroutine. }
 
+\subsection{Call Site Entries}
+\label{chap:callsiteentries}
+\textit{
+A call site entry provides a way to represent the static or dynamic 
+call graph of a program in the debugging information. It also provides
+information about how parameters are passed so that they may be more
+easily accessed by a debugger. Together with the \DWOPentryvalue{} opcode,
+call site entries can be also useful for computing values of variables 
+and expressions where some value is no longer present in the current 
+subroutine's registers or local stack frame, but it is known that the 
+values are equal to some parameter passed to the function.  
+The consumer can then use unwind
+information to find the caller and in the call site information sometimes
+find how to compute the value passed in a particular parameter.}
+
+A call site is represented by a debugging information entry with the tag
+\DWTAGcallsiteTARG{}.  The entry for a call site is owned by the innermost
+debugging information entry representing the scope within which the
+call is present in the source program.
+
+\textit{A scope entry (for example, for a lexical block) that would not 
+otherwise be present in the debugging information of a subroutine
+need not be introduced solely to represent the immediately containing scope
+of a call. The call site entry is owned by the innermost scope entry that
+is present.}
+
+A source call can be compiled into different types of machine code:
+\begin{itemize}
+\item
+A \textit{normal call} uses a call-like instruction which transfers control to the start
+of some subprogram and leaves the call site location address somewhere where
+unwind information can find it.  
+\item
+A \textit{tail call} uses a jump-like instruction which
+transfers control to the start of some subprogram, but the call site location
+address is not preserved (and thus not available using the unwind information).  
+\item
+A \textit{tail recursion call} is a call
+to the current subroutine which is compiled as a loop into the middle of the
+current subroutine.
+\item
+An \textit{inline (or inlined) call} is a call to an inlined subprogram,
+where at least one instruction has the location of the inlined subprogram
+or any of its blocks or inlined subprograms. 
+\end{itemize}
+
+There are also different types of \doublequote{optimized out} calls:
+\begin{itemize}
+\item
+An \textit{optimized out (normal) call} is a call that is in unreachable code that 
+has not been emitted (such as, for example, the call to \texttt{foo} in 
+\texttt{if (0) foo();}).  
+\item
+An \textit{optimized out inline call}
+is a call to an inlined subprogram which either did not expand to any instructions
+or only parts of instructions belong to it and for debug information purposes those
+instructions are given a location in the caller.
+\end{itemize}
+
+\DWTAGcallsite{} entries describe normal and tail calls but not tail recursion calls,
+while \DWTAGinlinedsubroutine{} entries describe inlined calls 
+(see Section \refersec{chap:inlinedsubroutines}).
+
+The call site entry has a 
+\DWATcallreturnpcTARG{} \addtoindexi{attribute}{call return pc attribute} 
+which is the return address after the call.  
+The value of this attribute corresponds to the return address computed by 
+call frame information in the called subprogram 
+(see Section \refersec{datarep:callframeinformation}).
+
+\textit{On many architectures the return address is the address immediately following the
+call instruction, but on architectures with delay slots it might
+be an address after the delay slot of the call.}
+
+The call site entry may have a 
+\DWATcallpcTARG{} \addtoindexi{attribute}{call pc attribute} which is the
+address of the call instruction.
+
+If the call site entry corresponds to a tail call, it has the 
+\DWATcalltailcallTARG{} \addtoindexi{attribute}{call tail call attribute},
+which is a \CLASSflag.
+
+The call site entry may have a 
+\DWATcalloriginTARG{} \addtoindex{attribute}{call origin attribute}
+which is a \CLASSreference.  For direct calls or jumps where the called subprogram is
+known it is a reference to the called subprogram's debugging
+information entry.  For indirect calls it may be a reference to a
+\DWTAGvariable{}, \DWTAGformalparameter{} or \DWTAGmember{} entry representing
+the subroutine pointer that is called.
+
+The call site may have a 
+\DWATcalltargetTARG{} \addtoindexi{attribute}{call target attribute} which is
+a DWARF expression.  For indirect calls or jumps where it is unknown at
+compile time which subprogram will be called the expression computes the
+address of the subprogram that will be called.  The DWARF expression should
+not use register or memory locations that might be clobbered by the call.
+
+The call site entry may have a 
+\DWATcalltargetclobberedTARG{} \addtoindexi{attribute}{call target clobbered attribute}
+which is a DWARF expression.  For indirect calls or jumps where the
+address is not computable without use of registers or memory locations that
+might be clobbered by the call the \DWATcalltargetclobberedNAME{}
+attribute is used instead of the \DWATcalltarget{} attribute.
+
+The call site entry may have a \DWATtype{} attribute referencing 
+a debugging information entry for the type of the called function.  
+When \DWATcallorigin{} is present, \DWATtype{} is usually omitted.
+
+The call site entry may have \DWATcallfile{}, \DWATcallline{} and
+\DWATcallcolumn{} attributes, each of whose value is an integer constant.
+These attributes represent the source file, source line number, and source
+column number, respectively, of the first character of the call statement or
+expression.  The call file, call line, and call column attributes are
+interpreted in the same way as the declaration file, declaration
+line, and declaration column attributes, respectively 
+(see Section \refersec{chap:declarationcoordinates}).
+
+\textit{The call file, call line and call column coordinates do not describe the
+coordinates of the subroutine declaration that was inlined, rather they describe
+the coordinates of the call.}
+
+The call site entry may own \DWTAGcallsiteparameterTARG{} debugging information
+entries\index{call site parameter entry} representing the parameters passed to the call.
+Each such entry has a \DWATlocation{} attribute which is a location expression.
+This location expression describes where the parameter is passed
+in (usually either some register, or a memory location expressible as the
+contents of the stack register plus some offset).
+
+Each \DWTAGcallsiteparameterTARG{} entry may have a 
+\DWATcallvalue{} \addtoindexi{attribute}{call value attribute}
+which is a DWARF expression.  This expression computes the value
+passed for that parameter.  The expression should not use registers or memory
+locations that might be clobbered by the call, as it might be evaluated after
+unwinding from the called function back to the caller.  If it is not
+possible to avoid registers or memory locations that might be clobbered by
+the call in the expression, then the \DWATcallvalueNAME{} attribute should
+not be provided.
+
+\textit{The reason for the restriction is that the value of the parameter may be
+needed in the middle of the callee, where the call clobbered registers or
+memory might be already clobbered, and if the consumer was not assured by
+the producer it can safely use those values, the consumer could not safely
+use the values at all.}
+
+For parameters passed by reference, where the code passes a pointer to
+a location which contains the parameter, or for reference type parameters
+the \DWTAGcallsiteparameter{} entry may also have 
+\DWATcalldatalocation{} \addtoindexi{attribute}{call data location attribute}
+whose value is a location expression and a
+\DWATcalldatavalue{} \addtoindexi{attribute}{call data value attribute}
+whose value is a DWARF expression.  The \DWATcalldatalocationNAME{} attribute 
+describes where the referenced value lives during the call.  If it is just 
+\DWOPpushobjectaddress{}, it may be left out.  The 
+\DWATcalldatavalueNAME{} attribute describes the value in that location. 
+The expression should not use registers or memory
+locations that might be clobbered by the call, as it might be evaluated after
+unwinding from the called function back to the caller.
+
+Each call site parameter entry may also have a 
+\DWATcallparameter{} \addtoindexi{attribute}{call parameter entry}
+which contains a reference to a \DWTAGformalparameter{} entry,
+\DWATtype{} attribute referencing the type of the parameter or \DWATname{}
+attribute describing the parameter's name.
+
 
 
 \section{Lexical Block Entries}
@@ -2113,9 +2312,3 @@ The siblings immediately following
 a try \livelink{chap:tryblock}{block} entry are its
 corresponding catch \livelink{chap:catchblock}{block} entries.
 
-
-
-
-
-
-