2 .\" Manual page created with latex2man on Thu Aug 16 09:44:44 MDT 2007
3 .\" NOTE: This file is generated, DO NOT EDIT.
13 .TH "LIBUNWIND\-IA64" "3" "16 August 2007" "Programming Library " "Programming Library "
16 \-\- IA\-64\-specific support in libunwind
21 The IA\-64 version of libunwind
22 uses a platform\-string of
24 and, at least in theory, should be able to support all
25 operating systems adhering to the processor\-specific ABI defined for
26 the Itanium Processor Family. This includes both little\-endian Linux
27 and big\-endian HP\-UX. Furthermore, to make it possible for a single
28 library to unwind both 32\- and 64\-bit targets, the type
30 is always defined to be 64 bits wide (independent
31 of the natural word\-size of the host). Having said that, the current
32 implementation has been tested only with IA\-64 Linux.
34 When targeting IA\-64, the libunwind
35 header file defines the
37 as 1 and the macro UNW_TARGET
38 as ``ia64\&'' (without the quotation marks). The former makes it
39 possible for platform\-dependent unwind code to use
40 conditional\-compilation to select an appropriate implementation. The
41 latter is useful for stringification purposes and to construct
42 target\-platform\-specific symbols.
44 One special feature of IA\-64 is the use of NaT bits to support
45 speculative execution. Often, NaT bits are thought of as the ``65\-th
46 bit\&'' of a general register. However, to make everything fit into
47 64\-bit wide unw_word_t
50 NaT\-bits like separate boolean registers, whose 64\-bit value is either
51 TRUE (non\-zero) or FALSE (zero).
56 The machine\-state (set of registers) that is accessible through
58 depends on the type of stack frame that a cursor
59 points to. For normal frames, all ``preserved\&'' (callee\-saved)
60 registers are accessible. For signal\-trampoline frames, all registers
61 (including ``scratch\&'' (caller\-saved) registers) are accessible. Most
62 applications do not have to worry a\-priori about which registers are
63 accessible when. In case of doubt, it is always safe to \fItry\fP
65 access a register (via unw_get_reg()
68 and if the register isn\&'t accessible, the
69 call will fail with a return\-value of \-UNW_EBADREG\&.
71 As a special exception to the above general rule, scratch registers
73 are always accessible, even in normal
74 frames. This makes it possible to pass arguments, e.g., to exception
77 For a detailed description of the IA\-64 register usage convention,
78 please see the ``Itanium Software Conventions and Runtime Architecture
79 Guide\&'', available at:
81 \fBhttp://www.intel.com/design/itanium/downloads/245358.htm\fP
88 The IA\-64\-version of libunwind
89 defines three kinds of register
90 name macros: frame\-register macros, normal register macros, and
91 convenience macros. Below, we describe each kind in turn:
93 .SS FRAME\-REGISTER MACROS
95 Frame\-registers are special (pseudo) registers because they always
96 have a valid value, even though sometimes they do not get saved
97 explicitly (e.g., if a memory stack frame is 16 bytes in size, the
98 previous stack\-pointer value can be calculated simply as
100 so there is no need to save the stack\-pointer
101 explicitly). Moreover, the set of frame register values uniquely
102 identifies a stack frame. The IA\-64 architecture defines two stacks
103 (a memory and a register stack). Including the instruction\-pointer
104 (IP), this means there are three frame registers:
107 Contains the instruction pointer (IP, or
108 ``program counter\&'') of the current stack frame. Given this value,
109 the remaining machine\-state corresponds to the register\-values that
110 were present in the CPU when it was just about to execute the
111 instruction pointed to by UNW_IA64_IP\&.
113 this frame\-register encode the slot number of the instruction.
115 Due to the way the call instruction works on IA\-64,
116 the slot number is usually zero, but can be non\-zero, e.g., in the
117 stack\-frame of a signal\-handler trampoline.
120 Contains the (memory) stack\-pointer
124 Contains the register backing\-store
125 pointer (BSP). \fBNote:\fP
126 the value in this register is equal
127 to the contents of register ar.bsp
129 instruction at UNW_IA64_IP
130 was about to begin execution.
132 .SS NORMAL REGISTER MACROS
134 The following normal register name macros are available:
137 The base\-index for general (integer)
138 registers. Add an index in the range from 0..127 to get a
139 particular general register. For example, to access r4,
140 the index UNW_IA64_GR+4
146 and any attempt to write them will result in an error
147 (\-UNW_EREADONLYREG).
150 read\-only, libunwind
151 will automatically adjust its value if
152 the instruction\-pointer (UNW_IA64_IP)
154 example, if UNW_IA64_IP
155 is set to a value inside a
159 will return the global\-pointer
160 value for this function.
163 The base\-index for the NaT bits of the
164 general (integer) registers. A non\-zero value in these registers
165 corresponds to a set NaT\-bit. Add an index in the range from 0..127
166 to get a particular NaT\-bit register. For example, to access the
168 the index UNW_IA64_NAT+4
172 The base\-index for floating\-point
173 registers. Add an index in the range from 0..127 to get a
174 particular floating\-point register. For example, to access
176 the index UNW_IA64_FR+2
180 are read\-only, and any
181 attempt to write to indices UNW_IA64_FR+0
184 will result in an error
185 (\-UNW_EREADONLYREG).
188 The base\-index for application
189 registers. Add an index in the range from 0..127 to get a
190 particular application register. For example, to access
192 the index UNW_IA64_AR+40
194 used. The IA\-64 architecture defines several application registers
195 as ``reserved for future use\&''\&. Attempting to access such registers
196 results in an error (\-UNW_EBADREG).
199 The base\-index for branch registers.
200 Add an index in the range from 0..7 to get a particular branch
201 register. For example, to access b6,
207 Contains the set of predicate registers.
208 This 64\-bit wide register contains registers p0
211 in the ``broad\-side\&'' format. Just like with the
212 ``move predicates\&'' instruction, the registers are mapped as if
214 were set to 0. Thus, in general the value of
215 predicate register pN
216 with N>=16 can be found
217 in bit 16 + ((N\-16)+CFM.rrb.pr) % 48\&.
220 Contains the current\-frame\-mask
223 .SS CONVENIENCE MACROS
225 Convenience macros are simply aliases for certain frequently used
229 Alias for UNW_IA64_GR+1,
230 the global\-pointer register.
233 Alias for UNW_IA64_GR+13,
234 the thread\-pointer register.
237 Alias for UNW_IA64_GR+16,
238 the register\-stack configuration register.
243 This register index accesses the
244 value of register ar.bsp
245 as of the time it was last saved
246 explicitly. This is rarely what you want. Normally, you\&'ll want to
250 UNW_IA64_AR_BSPSTORE:
251 Alias for UNW_IA64_GR+18,
252 the register\-backing store write pointer.
255 Alias for UNW_IA64_GR+19,
256 the register\-backing store NaT\-collection register.
259 Alias for UNW_IA64_GR+32,
260 the compare\-and\-swap value register.
263 Alias for UNW_IA64_GR+25,
264 the compare\-and\-swap\-data register (used by 16\-byte atomic operations).
267 Alias for UNW_IA64_GR+36,
268 the user NaT\-collection register.
271 Alias for UNW_IA64_GR+40,
272 the floating\-point status (and control) register.
275 Alias for UNW_IA64_GR+64,
276 the previous frame\-state register.
279 Alias for UNW_IA64_GR+65
280 the loop\-count register.
283 Alias for UNW_IA64_GR+66,
284 the epilogue\-count register.
286 .SH THE UNWIND\-CONTEXT TYPE
289 On IA\-64, unw_context_t
290 is simply an alias for
292 (as defined by the Single UNIX Spec). This implies
293 that it is possible to initialize a value of this type not just with
295 but also with getcontext(),
297 example. However, since this is an IA\-64\-specific extension to
299 portable code should not rely on this equivalence.
309 David Mosberger\-Tang
311 Email: \fBdmosberger@gmail.com\fP
313 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
314 .\" NOTE: This file is generated, DO NOT EDIT.