From bd2b4658cb223d68a339dc9b838aa7f9eb3a6c3e Mon Sep 17 00:00:00 2001 From: "mostang.com!davidm" Date: Sat, 18 Jan 2003 08:10:40 +0000 Subject: [PATCH] (Logical change 1.38) --- doc/libunwind-ia64.man | 297 +++++++++++++++++++++++++++++++++++++++++ doc/libunwind-ia64.tex | 211 +++++++++++++++++++++++++++++ 2 files changed, 508 insertions(+) diff --git a/doc/libunwind-ia64.man b/doc/libunwind-ia64.man index e69de29b..fd7b7434 100644 --- a/doc/libunwind-ia64.man +++ b/doc/libunwind-ia64.man @@ -0,0 +1,297 @@ +'\" t +.\" Manual page created with latex2man on Fri Jan 17 15:46:04 PST 2003 +.\" NOTE: This file is generated, DO NOT EDIT. +.de Vb +.ft CW +.nf +.. +.de Ve +.ft R + +.fi +.. +.TH "LIBUNWIND\-IA64" "3" "17 January 2003" "Programming Library " "Programming Library " +.SH NAME + +libunwind\-ia64 \-\- IA\-64\-specific support in libunwind +.PP +.SH INTRODUCTION + +.PP +The IA\-64 version of libunwind +uses a platform\-string of +ia64 +and, at least in theory, should be able to support all +operating systems adhering to the processor\-specific ABI defined for +the Itanium Processor Family. This includes both little\-endian Linux +and big\-endian HP\-UX. Furthermore, to make it possible for a single +library to unwind both 32\- and 64\-bit targets, the type +unw_word_t +is always defined to be 64 bits wide (independent +of the natural word\-size of the host). Having said that, the current +implementation has been tested only with IA\-64 Linux. +.PP +When targeting IA\-64, the libunwind +header file defines the +macro UNW_TARGET_IA64 +as 1 and the macro UNW_TARGET +as ``ia64\&'' (without the quotation marks). The former makes it +possible for platform\-dependent unwind code to use +conditional\-compilation to select an appropriate implementation. The +latter is useful for stringification purposes and to construct +target\-platform\-specific symbols. +.PP +One special feature of IA\-64 is the use of NaT bits to support +speculative execution. Often, NaT bits are thought of as the ``65\-th +bit\&'' of a general register. However, to make everything fit into +64\-bit wide unw_word_t +values, libunwind +treats the +NaT\-bits like separate boolean registers, whose 64\-bit value is either +TRUE (non\-zero) or FALSE (zero). +.PP +.SH MACHINE\-STATE + +.PP +The machine\-state (set of registers) that is accessible through +libunwind +depends on the type of stack frame that a cursor +points to. For normal frames, all ``preserved\&'' (callee\-saved) +registers are accessible. For signal\-trampoline frames, all registers +(including ``scratch\&'' (caller\-saved) registers) are accessible. Most +applications do not have to worry a\-priori about which registers are +accessible when. In case of doubt, it is always safe to \fItry\fP +to +access a register (via unw_get_reg() +or +unw_get_fpreg()) +and if the register isn\&'t accessible, the +call will fail with a return\-value of \-UNW_EBADREG\&. +.PP +As a special exception to the above general rule, scratch registers +r15\-r18 +are always accessible, even in normal +frames. This makes it possible to pass arguments, e.g., to exception +handlers. +.PP +For a detailed description of the IA\-64 register usage convention, +please see the ``Itanium Software Conventions and Runtime Architecture +Guide\&'', available at: +.ce 100 +\fBhttp://www.intel.com/design/itanium/downloads/245358.htm\fP +.ce 0 + +.PP +.SH REGISTER NAMES + +.PP +The IA\-64\-version of libunwind +defines three kinds of register +name macros: frame\-register macros, normal register macros, and +convenience macros. Below, we describe each kind in turn: +.PP +.SS FRAME\-REGISTER MACROS +.PP +Frame\-registers are special (pseudo) registers because they always +have a valid value, even though sometimes they do not get saved +explicitly (e.g., if a memory stack frame is 16 bytes in size, the +previous stack\-pointer value can be calculated simply as +sp+16, +so there is no need to save the stack\-pointer +explicitly). Moreover, the set of frame register values uniquely +identifies a stack frame. The IA\-64 architecture defines two stacks +(a memory and a register stack). Including the instruction\-pointer +(IP), this means there are three frame registers: +.TP +UNW_IA64_IP: + Contains the instruction pointer (IP, or +``program counter\&'') of the current stack frame. Given this value, +the remaining machine\-state corresponds to the register\-values that +were present in the CPU when it was just about to execute the +instruction pointed to by UNW_IA64_IP\&. +Bits 0 and 1 of +this frame\-register encode the slot number of the instruction. +\fBNote:\fP +Due to the way the call instruction works on IA\-64, +the slot number is usually zero, but can be non\-zero, e.g., in the +stack\-frame of a signal\-handler trampoline. +.TP +UNW_IA64_SP: + Contains the (memory) stack\-pointer +value (SP). This frame\-register is read\-only. +.TP +UNW_IA64_BSP: + Contains the register backing\-store +pointer (BSP). This frame\-register is read\-only. \fBNote:\fP +the value in this register is equal to the contents of register +ar.bsp +at the time the instruction at UNW_IA64_IP +was about to begin execution. +.PP +.SS NORMAL REGISTER MACROS +.PP +The following normal register name macros are available: +.TP +UNW_IA64_GR: + The base\-index for general (integer) +registers. Add an index in the range from 0..127 to get a +particular general register. For example, to access r4, +the index UNW_IA64_GR+4 +should be used. Register +r0 +is read\-only, and any attempt to write to index +UNW_IA64_GR+0 +will result in an error +(\-UNW_EREADONLYREG). +.TP +UNW_IA64_NAT: + The base\-index for the NaT bits of the +general (integer) registers. A non\-zero value in these registers +corresponds to a set NaT\-bit. Add an index in the range from 0..127 +to get a particular NaT\-bit register. For example, to access the +NaT bit of r4, +the index UNW_IA64_NAT+4 +should be used. +.TP +UNW_IA64_FR: + The base\-index for floating\-point +registers. Add an index in the range from 0..127 to get a +particular floating\-point register. For example, to access +f2, +the index UNW_IA64_FR+2 +should be +used. Registers f0 +and f1 +are read\-only, and any +attempt to write to indices UNW_IA64_FR+0 +or +UNW_IA64_FR+1 +will result in an error +(\-UNW_EREADONLYREG). +.TP +UNW_IA64_AR: + The base\-index for application +registers. Add an index in the range from 0..127 to get a +particular application register. For example, to access +ar40, +the index UNW_IA64_AR+40 +should be +used. The IA\-64 architecture defines several application registers +as ``reserved for future use\&''\&. Attempting to access such registers +results in an error (\-UNW_EBADREG). +.TP +UNW_IA64_BR: + The base\-index for branch registers. +Add an index in the range from 0..7 to get a particular branch +register. For example, to access b6, +the index +UNW_IA64_BR+6 +should be used. +.TP +UNW_IA64_PR: + Contains the set of predicate registers. +This 64\-bit wide register contains registers p0 +through +p63 +in the ``broad\-side\&'' format (i.e., p0 +corresponds to bit 0, p1 +to bit 1, and so on). +.TP +UNW_IA64_CFM: + Contains the current\-frame\-mask +register. +.PP +.SS CONVENIENCE MACROS +.PP +Convenience macros are simply aliases for certain frequently used +registers: +.TP +UNW_IA64_GP: + Alias for UNW_IA64_GR+1\&. +The global\-pointer register. For unwinding\-purposes, this register +is treated as read\-only. +.TP +UNW_IA64_TP: + Alias for UNW_IA64_GR+13\&. +The thread\-pointer register. For unwinding\-purposes, this register is +treated as read\-only. +.TP +UNW_IA64_AR_RSC: + Alias for UNW_IA64_GR+16\&. +The register\-stack configuration register. +.TP +UNW_IA64_AR_BSP: + Alias for +UNW_IA64_GR+17\&. +This register index accesses the +value of register ar.bsp +as of the time it was last saved +explicitly. This is rarely what you want. Normally, you\&'ll want to +use UNW_IA64_BSP +instead. +.TP +UNW_IA64_AR_BSPSTORE: + Alias for UNW_IA64_GR+18\&. +The register\-backing store write pointer. +.TP +UNW_IA64_AR_RNAT: + Alias for UNW_IA64_GR+19\&. +The register\-backing store NaT\-collection register. +.TP +UNW_IA64_AR_CCV: + Alias for UNW_IA64_GR+32\&. +The compare\-and\-swap value register. +.TP +UNW_IA64_AR_UNAT: + Alias for UNW_IA64_GR+36\&. +The user NaT\-collection register. +.TP +UNW_IA64_AR_FPSR: + Alias for UNW_IA64_GR+40\&. +The floating\-point status (and control) register. +.TP +UNW_IA64_AR_PFS: + Alias for UNW_IA64_GR+64\&. +The previous frame\-state register. +.TP +UNW_IA64_AR_LC: + Alias for UNW_IA64_GR+65\&. +The loop\-count register. +.TP +UNW_IA64_AR_EC: + Alias for UNW_IA64_GR+66\&. +The epilogue\-count register. +.PP +.SH THE UNWIND\-CONTEXT TYPE + +.PP +On IA\-64, unw_context_t +is simply an alias for +ucontext_t +(as defined by the Single UNIX Spec). This implies +that it is possible to initialize a value of this type not just with +unw_getcontext(), +but also with getcontext(), +for +example. However, since this is an IA\-64\-specific extension to +libunwind, +portable code should not rely on this equivalence. +.PP +.SH SEE ALSO + +.PP +libunwind(3) +.PP +.SH AUTHOR + +.PP +David Mosberger\-Tang +.br +Hewlett\-Packard Labs +.br +Palo\-Alto, CA 94304 +.br +Email: \fBdavidm@hpl.hp.com\fP +.br +WWW: \fBhttp://www.hpl.hp.com/research/linux/libunwind/\fP\&. +.\" NOTE: This file is generated, DO NOT EDIT. diff --git a/doc/libunwind-ia64.tex b/doc/libunwind-ia64.tex index e69de29b..23d15c5a 100644 --- a/doc/libunwind-ia64.tex +++ b/doc/libunwind-ia64.tex @@ -0,0 +1,211 @@ +\documentclass{article} +\usepackage[fancyhdr,pdf]{latex2man} + +\input{common.tex} + +\begin{document} + +\begin{Name}{3}{libunwind-ia64}{David Mosberger-Tang}{Programming Library}{IA-64-specific support in libunwind} + libunwind-ia64 -- IA-64-specific support in libunwind +\end{Name} + + +\section{Introduction} + +The IA-64 version of \Prog{libunwind} uses a platform-string of +\texttt{ia64} and, at least in theory, should be able to support all +operating systems adhering to the processor-specific ABI defined for +the Itanium Processor Family. This includes both little-endian Linux +and big-endian HP-UX. Furthermore, to make it possible for a single +library to unwind both 32- and 64-bit targets, the type +\Type{unw\_word\_t} is always defined to be 64 bits wide (independent +of the natural word-size of the host). Having said that, the current +implementation has been tested only with IA-64 Linux. + +When targeting IA-64, the \Prog{libunwind} header file defines the +macro \Const{UNW\_TARGET\_IA64} as 1 and the macro \Const{UNW\_TARGET} +as ``ia64'' (without the quotation marks). The former makes it +possible for platform-dependent unwind code to use +conditional-compilation to select an appropriate implementation. The +latter is useful for stringification purposes and to construct +target-platform-specific symbols. + +One special feature of IA-64 is the use of NaT bits to support +speculative execution. Often, NaT bits are thought of as the ``65-th +bit'' of a general register. However, to make everything fit into +64-bit wide \Type{unw\_word\_t} values, \Prog{libunwind} treats the +NaT-bits like separate boolean registers, whose 64-bit value is either +TRUE (non-zero) or FALSE (zero). + + +\section{Machine-State} + +The machine-state (set of registers) that is accessible through +\Prog{libunwind} depends on the type of stack frame that a cursor +points to. For normal frames, all ``preserved'' (callee-saved) +registers are accessible. For signal-trampoline frames, all registers +(including ``scratch'' (caller-saved) registers) are accessible. Most +applications do not have to worry a-priori about which registers are +accessible when. In case of doubt, it is always safe to \emph{try} to +access a register (via \Func{unw\_get\_reg}() or +\Func{unw\_get\_fpreg}()) and if the register isn't accessible, the +call will fail with a return-value of \texttt{-}\Const{UNW\_EBADREG}. + +As a special exception to the above general rule, scratch registers +\texttt{r15}-\texttt{r18} are always accessible, even in normal +frames. This makes it possible to pass arguments, e.g., to exception +handlers. + +For a detailed description of the IA-64 register usage convention, +please see the ``Itanium Software Conventions and Runtime Architecture +Guide'', available at: +\begin{center} + \URL{http://www.intel.com/design/itanium/downloads/245358.htm} +\end{center} + + +\section{Register Names} + +The IA-64-version of \Prog{libunwind} defines three kinds of register +name macros: frame-register macros, normal register macros, and +convenience macros. Below, we describe each kind in turn: + + +\subsection{Frame-register Macros} + +Frame-registers are special (pseudo) registers because they always +have a valid value, even though sometimes they do not get saved +explicitly (e.g., if a memory stack frame is 16 bytes in size, the +previous stack-pointer value can be calculated simply as +\texttt{sp+16}, so there is no need to save the stack-pointer +explicitly). Moreover, the set of frame register values uniquely +identifies a stack frame. The IA-64 architecture defines two stacks +(a memory and a register stack). Including the instruction-pointer +(IP), this means there are three frame registers: +\begin{Description} +\item[\Const{UNW\_IA64\_IP}:] Contains the instruction pointer (IP, or + ``program counter'') of the current stack frame. Given this value, + the remaining machine-state corresponds to the register-values that + were present in the CPU when it was just about to execute the + instruction pointed to by \Const{UNW\_IA64\_IP}. Bits 0 and 1 of + this frame-register encode the slot number of the instruction. + \textbf{Note:} Due to the way the call instruction works on IA-64, + the slot number is usually zero, but can be non-zero, e.g., in the + stack-frame of a signal-handler trampoline. +\item[\Const{UNW\_IA64\_SP}:] Contains the (memory) stack-pointer + value (SP). This frame-register is read-only. +\item[\Const{UNW\_IA64\_BSP}:] Contains the register backing-store + pointer (BSP). This frame-register is read-only. \textbf{Note:} + the value in this register is equal to the contents of register + \texttt{ar.bsp} at the time the instruction at \Const{UNW\_IA64\_IP} + was about to begin execution. +\end{Description} + + +\subsection{Normal Register Macros} + +The following normal register name macros are available: +\begin{Description} +\item[\Const{UNW\_IA64\_GR}:] The base-index for general (integer) + registers. Add an index in the range from 0..127 to get a + particular general register. For example, to access \texttt{r4}, + the index \Const{UNW\_IA64\_GR}\texttt{+4} should be used. Register + \texttt{r0} is read-only, and any attempt to write to index + \Const{UNW\_IA64\_GR}\texttt{+0} will result in an error + (\texttt{-}\Const{UNW\_EREADONLYREG}). +\item[\Const{UNW\_IA64\_NAT}:] The base-index for the NaT bits of the + general (integer) registers. A non-zero value in these registers + corresponds to a set NaT-bit. Add an index in the range from 0..127 + to get a particular NaT-bit register. For example, to access the + NaT bit of \texttt{r4}, the index \Const{UNW\_IA64\_NAT}\texttt{+4} + should be used. +\item[\Const{UNW\_IA64\_FR}:] The base-index for floating-point + registers. Add an index in the range from 0..127 to get a + particular floating-point register. For example, to access + \texttt{f2}, the index \Const{UNW\_IA64\_FR}\texttt{+2} should be + used. Registers \texttt{f0} and \texttt{f1} are read-only, and any + attempt to write to indices \Const{UNW\_IA64\_FR}\texttt{+0} or + \Const{UNW\_IA64\_FR}\texttt{+1} will result in an error + (\texttt{-}\Const{UNW\_EREADONLYREG}). +\item[\Const{UNW\_IA64\_AR}:] The base-index for application + registers. Add an index in the range from 0..127 to get a + particular application register. For example, to access + \texttt{ar40}, the index \Const{UNW\_IA64\_AR}\texttt{+40} should be + used. The IA-64 architecture defines several application registers + as ``reserved for future use''. Attempting to access such registers + results in an error (\texttt{-}\Const{UNW\_EBADREG}). +\item[\Const{UNW\_IA64\_BR}:] The base-index for branch registers. + Add an index in the range from 0..7 to get a particular branch + register. For example, to access \texttt{b6}, the index + \Const{UNW\_IA64\_BR}\texttt{+6} should be used. +\item[\Const{UNW\_IA64\_PR}:] Contains the set of predicate registers. + This 64-bit wide register contains registers \texttt{p0} through + \texttt{p63} in the ``broad-side'' format (i.e., \texttt{p0} + corresponds to bit 0, \texttt{p1} to bit 1, and so on). +\item[\Const{UNW\_IA64\_CFM}:] Contains the current-frame-mask + register. +\end{Description} + + +\subsection{Convenience Macros} + +Convenience macros are simply aliases for certain frequently used +registers: +\begin{Description} +\item[\Const{UNW\_IA64\_GP}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+1}. + The global-pointer register. For unwinding-purposes, this register + is treated as read-only. +\item[\Const{UNW\_IA64\_TP}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+13}. + The thread-pointer register. For unwinding-purposes, this register is + treated as read-only. +\item[\Const{UNW\_IA64\_AR\_RSC}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+16}. + The register-stack configuration register. +\item[\Const{UNW\_IA64\_AR\_BSP}:] Alias for + \Const{UNW\_IA64\_GR}\texttt{+17}. This register index accesses the + value of register \texttt{ar.bsp} as of the time it was last saved + explicitly. This is rarely what you want. Normally, you'll want to + use \Const{UNW\_IA64\_BSP} instead. +\item[\Const{UNW\_IA64\_AR\_BSPSTORE}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+18}. + The register-backing store write pointer. +\item[\Const{UNW\_IA64\_AR\_RNAT}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+19}. + The register-backing store NaT-collection register. +\item[\Const{UNW\_IA64\_AR\_CCV}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+32}. + The compare-and-swap value register. +\item[\Const{UNW\_IA64\_AR\_UNAT}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+36}. + The user NaT-collection register. +\item[\Const{UNW\_IA64\_AR\_FPSR}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+40}. + The floating-point status (and control) register. +\item[\Const{UNW\_IA64\_AR\_PFS}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+64}. + The previous frame-state register. +\item[\Const{UNW\_IA64\_AR\_LC}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+65}. + The loop-count register. +\item[\Const{UNW\_IA64\_AR\_EC}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+66}. + The epilogue-count register. +\end{Description} + + +\section{The Unwind-Context Type} + +On IA-64, \Type{unw\_context\_t} is simply an alias for +\Type{ucontext\_t} (as defined by the Single UNIX Spec). This implies +that it is possible to initialize a value of this type not just with +\Func{unw\_getcontext}(), but also with \Func{getcontext}(), for +example. However, since this is an IA-64-specific extension to +\Prog{libunwind}, portable code should not rely on this equivalence. + + +\section{See Also} + +\SeeAlso{libunwind(3)} + +\section{Author} + +\noindent +David Mosberger-Tang\\ +Hewlett-Packard Labs\\ +Palo-Alto, CA 94304\\ +Email: \Email{davidm@hpl.hp.com}\\ +WWW: \URL{http://www.hpl.hp.com/research/linux/libunwind/}. +\LatexManEnd + +\end{document}