1 \documentclass{article} 2 \usepackage[fancyhdr,pdf]{latex2man} 3 4 \input{common.tex} 5 6 \begin{document} 7 8 \begin{Name}{3}{libunwind-ia64}{David Mosberger-Tang}{Programming Library}{IA-64-specific support in libunwind}libunwind-ia64 -- IA-64-specific support in libunwind 9 \end{Name} 10 11 12 \section{Introduction} 13 14 The IA-64 version of \Prog{libunwind} uses a platform-string of 15 \texttt{ia64} and, at least in theory, should be able to support all 16 operating systems adhering to the processor-specific ABI defined for 17 the Itanium Processor Family. This includes both little-endian Linux 18 and big-endian HP-UX. Furthermore, to make it possible for a single 19 library to unwind both 32- and 64-bit targets, the type 20 \Type{unw\_word\_t} is always defined to be 64 bits wide (independent 21 of the natural word-size of the host). Having said that, the current 22 implementation has been tested only with IA-64 Linux. 23 24 When targeting IA-64, the \Prog{libunwind} header file defines the 25 macro \Const{UNW\_TARGET\_IA64} as 1 and the macro \Const{UNW\_TARGET} 26 as ``ia64'' (without the quotation marks). The former makes it 27 possible for platform-dependent unwind code to use 28 conditional-compilation to select an appropriate implementation. The 29 latter is useful for stringification purposes and to construct 30 target-platform-specific symbols. 31 32 One special feature of IA-64 is the use of NaT bits to support 33 speculative execution. Often, NaT bits are thought of as the ``65-th 34 bit'' of a general register. However, to make everything fit into 35 64-bit wide \Type{unw\_word\_t} values, \Prog{libunwind} treats the 36 NaT-bits like separate boolean registers, whose 64-bit value is either 37 TRUE (non-zero) or FALSE (zero). 38 39 40 \section{Machine-State} 41 42 The machine-state (set of registers) that is accessible through 43 \Prog{libunwind} depends on the type of stack frame that a cursor 44 points to. For normal frames, all ``preserved'' (callee-saved) 45 registers are accessible. For signal-trampoline frames, all registers 46 (including ``scratch'' (caller-saved) registers) are accessible. Most 47 applications do not have to worry a-priori about which registers are 48 accessible when. In case of doubt, it is always safe to \emph{try} to 49 access a register (via \Func{unw\_get\_reg}() or 50 \Func{unw\_get\_fpreg}()) and if the register isn't accessible, the 51 call will fail with a return-value of \texttt{-}\Const{UNW\_EBADREG}. 52 53 As a special exception to the above general rule, scratch registers 54 \texttt{r15}-\texttt{r18} are always accessible, even in normal 55 frames. This makes it possible to pass arguments, e.g., to exception 56 handlers. 57 58 For a detailed description of the IA-64 register usage convention, 59 please see the ``Itanium Software Conventions and Runtime Architecture 60 Guide'', available at: 61 \begin{center} 62 \URL{http://www.intel.com/design/itanium/downloads/245358.htm} 63 \end{center} 64 65 66 \section{Register Names} 67 68 The IA-64-version of \Prog{libunwind} defines three kinds of register 69 name macros: frame-register macros, normal register macros, and 70 convenience macros. Below, we describe each kind in turn: 71 72 73 \subsection{Frame-register Macros} 74 75 Frame-registers are special (pseudo) registers because they always 76 have a valid value, even though sometimes they do not get saved 77 explicitly (e.g., if a memory stack frame is 16 bytes in size, the 78 previous stack-pointer value can be calculated simply as 79 \texttt{sp+16}, so there is no need to save the stack-pointer 80 explicitly). Moreover, the set of frame register values uniquely 81 identifies a stack frame. The IA-64 architecture defines two stacks 82 (a memory and a register stack). Including the instruction-pointer 83 (IP), this means there are three frame registers: 84 \begin{Description} 85 \item[\Const{UNW\_IA64\_IP}:] Contains the instruction pointer (IP, or 86 ``program counter'') of the current stack frame. Given this value, 87 the remaining machine-state corresponds to the register-values that 88 were present in the CPU when it was just about to execute the 89 instruction pointed to by \Const{UNW\_IA64\_IP}. Bits 0 and 1 of 90 this frame-register encode the slot number of the instruction. 91 \textbf{Note:} Due to the way the call instruction works on IA-64, 92 the slot number is usually zero, but can be non-zero, e.g., in the 93 stack-frame of a signal-handler trampoline. 94 \item[\Const{UNW\_IA64\_SP}:] Contains the (memory) stack-pointer 95 value (SP). 96 \item[\Const{UNW\_IA64\_BSP}:] Contains the register backing-store 97 pointer (BSP). \textbf{Note:} the value in this register is equal 98 to the contents of register \texttt{ar.bsp} at the time the 99 instruction at \Const{UNW\_IA64\_IP} was about to begin execution. 100 \end{Description} 101 102 103 \subsection{Normal Register Macros} 104 105 The following normal register name macros are available: 106 \begin{Description} 107 \item[\Const{UNW\_IA64\_GR}:] The base-index for general (integer) 108 registers. Add an index in the range from 0..127 to get a 109 particular general register. For example, to access \texttt{r4}, 110 the index \Const{UNW\_IA64\_GR}\texttt{+4} should be used. 111 Registers \texttt{r0} and \texttt{r1} (\texttt{gp}) are read-only, 112 and any attempt to write them will result in an error 113 (\texttt{-}\Const{UNW\_EREADONLYREG}). Even though \texttt{r1} is 114 read-only, \Prog{libunwind} will automatically adjust its value if 115 the instruction-pointer (\Const{UNW\_IA64\_IP}) is modified. For 116 example, if \Const{UNW\_IA64\_IP} is set to a value inside a 117 function \Func{func}(), then reading 118 \Const{UNW\_IA64\_GR}\texttt{+1} will return the global-pointer 119 value for this function. 120 \item[\Const{UNW\_IA64\_NAT}:] The base-index for the NaT bits of the 121 general (integer) registers. A non-zero value in these registers 122 corresponds to a set NaT-bit. Add an index in the range from 0..127 123 to get a particular NaT-bit register. For example, to access the 124 NaT bit of \texttt{r4}, the index \Const{UNW\_IA64\_NAT}\texttt{+4} 125 should be used. 126 \item[\Const{UNW\_IA64\_FR}:] The base-index for floating-point 127 registers. Add an index in the range from 0..127 to get a 128 particular floating-point register. For example, to access 129 \texttt{f2}, the index \Const{UNW\_IA64\_FR}\texttt{+2} should be 130 used. Registers \texttt{f0} and \texttt{f1} are read-only, and any 131 attempt to write to indices \Const{UNW\_IA64\_FR}\texttt{+0} or 132 \Const{UNW\_IA64\_FR}\texttt{+1} will result in an error 133 (\texttt{-}\Const{UNW\_EREADONLYREG}). 134 \item[\Const{UNW\_IA64\_AR}:] The base-index for application 135 registers. Add an index in the range from 0..127 to get a 136 particular application register. For example, to access 137 \texttt{ar40}, the index \Const{UNW\_IA64\_AR}\texttt{+40} should be 138 used. The IA-64 architecture defines several application registers 139 as ``reserved for future use''. Attempting to access such registers 140 results in an error (\texttt{-}\Const{UNW\_EBADREG}). 141 \item[\Const{UNW\_IA64\_BR}:] The base-index for branch registers. 142 Add an index in the range from 0..7 to get a particular branch 143 register. For example, to access \texttt{b6}, the index 144 \Const{UNW\_IA64\_BR}\texttt{+6} should be used. 145 \item[\Const{UNW\_IA64\_PR}:] Contains the set of predicate registers. 146 This 64-bit wide register contains registers \texttt{p0} through 147 \texttt{p63} in the ``broad-side'' format. Just like with the 148 ``move predicates'' instruction, the registers are mapped as if 149 \texttt{CFM.rrb.pr} were set to 0. Thus, in general the value of 150 predicate register \texttt{p}$N$ with $N$>=16 can be found 151 in bit \texttt{16 + (($N$-16)+CFM.rrb.pr) \% 48}. 152 \item[\Const{UNW\_IA64\_CFM}:] Contains the current-frame-mask 153 register. 154 \end{Description} 155 156 157 \subsection{Convenience Macros} 158 159 Convenience macros are simply aliases for certain frequently used 160 registers: 161 \begin{Description} 162 \item[\Const{UNW\_IA64\_GP}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+1}, 163 the global-pointer register. 164 \item[\Const{UNW\_IA64\_TP}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+13}, 165 the thread-pointer register. 166 \item[\Const{UNW\_IA64\_AR\_RSC}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+16}, 167 the register-stack configuration register. 168 \item[\Const{UNW\_IA64\_AR\_BSP}:] Alias for 169 \Const{UNW\_IA64\_GR}\texttt{+17}. This register index accesses the 170 value of register \texttt{ar.bsp} as of the time it was last saved 171 explicitly. This is rarely what you want. Normally, you'll want to 172 use \Const{UNW\_IA64\_BSP} instead. 173 \item[\Const{UNW\_IA64\_AR\_BSPSTORE}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+18}, 174 the register-backing store write pointer. 175 \item[\Const{UNW\_IA64\_AR\_RNAT}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+19}, 176 the register-backing store NaT-collection register. 177 \item[\Const{UNW\_IA64\_AR\_CCV}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+32}, 178 the compare-and-swap value register. 179 \item[\Const{UNW\_IA64\_AR\_CSD}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+25}, 180 the compare-and-swap-data register (used by 16-byte atomic operations). 181 \item[\Const{UNW\_IA64\_AR\_UNAT}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+36}, 182 the user NaT-collection register. 183 \item[\Const{UNW\_IA64\_AR\_FPSR}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+40}, 184 the floating-point status (and control) register. 185 \item[\Const{UNW\_IA64\_AR\_PFS}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+64}, 186 the previous frame-state register. 187 \item[\Const{UNW\_IA64\_AR\_LC}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+65} 188 the loop-count register. 189 \item[\Const{UNW\_IA64\_AR\_EC}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+66}, 190 the epilogue-count register. 191 \end{Description} 192 193 194 \section{The Unwind-Context Type} 195 196 On IA-64, \Type{unw\_context\_t} is simply an alias for 197 \Type{ucontext\_t} (as defined by the Single UNIX Spec). This implies 198 that it is possible to initialize a value of this type not just with 199 \Func{unw\_getcontext}(), but also with \Func{getcontext}(), for 200 example. However, since this is an IA-64-specific extension to 201 \Prog{libunwind}, portable code should not rely on this equivalence. 202 203 204 \section{See Also} 205 206 \SeeAlso{libunwind(3)} 207 208 \section{Author} 209 210 \noindent 211 David Mosberger-Tang\\ 212 Email: \Email{dmosberger (a] gmail.com}\\ 213 WWW: \URL{http://www.nongnu.org/libunwind/}. 214 \LatexManEnd 215 216 \end{document} 217
