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