1LIBUNWIND-IA64(3) Programming Library LIBUNWIND-IA64(3)
2
6 libunwind-ia64 -- IA-64-specific support in libunwind
7
9 The IA-64 version of libunwind uses a platform-string of ia64 and, at
10 least in theory, should be able to support all operating systems adher‐
11 ing to the processor-specific ABI defined for the Itanium Processor
12 Family. This includes both little-endian Linux and big-endian HP-UX.
13 Furthermore, to make it possible for a single library to unwind both
14 32- and 64-bit targets, the type unw_word_t is always defined to be 64
15 bits wide (independent of the natural word-size of the host). Having
16 said that, the current implementation has been tested only with IA-64
17 Linux.
18 When targeting IA-64, the libunwind header file defines the macro
20 UNW_TARGET_IA64 as 1 and the macro UNW_TARGET as ``ia64'' (without the
21 quotation marks). The former makes it possible for platform-dependent
22 unwind code to use conditional-compilation to select an appropriate
23 implementation. The latter is useful for stringification purposes and
24 to construct target-platform-specific symbols.
25 One special feature of IA-64 is the use of NaT bits to support specula‐
27 tive execution. Often, NaT bits are thought of as the ``65-th bit'' of
28 a general register. However, to make everything fit into 64-bit wide
29 unw_word_t values, libunwind treats the NaT-bits like separate boolean
30 registers, whose 64-bit value is either TRUE (non-zero) or FALSE
31 (zero).
32
34 The machine-state (set of registers) that is accessible through libun‐
35 wind depends on the type of stack frame that a cursor points to. For
36 normal frames, all ``preserved'' (callee-saved) registers are accessi‐
37 ble. For signal-trampoline frames, all registers (including ``scratch''
38 (caller-saved) registers) are accessible. Most applications do not have
39 to worry a-priori about which registers are accessible when. In case of
40 doubt, it is always safe to try to access a register (via unw_get_reg()
41 or unw_get_fpreg()) and if the register isn't accessible, the call will
42 fail with a return-value of -UNW_EBADREG.
43 As a special exception to the above general rule, scratch registers
45 r15-r18 are always accessible, even in normal frames. This makes it
46 possible to pass arguments, e.g., to exception handlers.
47 For a detailed description of the IA-64 register usage convention,
49 please see the ``Itanium Software Conventions and Runtime Architecture
50 Guide'', available at:
51 http://www.intel.com/design/itanium/downloads/245358.htm
52
55 The IA-64-version of libunwind defines three kinds of register name
56 macros: frame-register macros, normal register macros, and convenience
57 macros. Below, we describe each kind in turn:
58 FRAME-REGISTER MACROS
60 Frame-registers are special (pseudo) registers because they always have
61 a valid value, even though sometimes they do not get saved explicitly
62 (e.g., if a memory stack frame is 16 bytes in size, the previous
63 stack-pointer value can be calculated simply as sp+16, so there is no
64 need to save the stack-pointer explicitly). Moreover, the set of frame
65 register values uniquely identifies a stack frame. The IA-64 architec‐
66 ture defines two stacks (a memory and a register stack). Including the
67 instruction-pointer (IP), this means there are three frame registers:
68 UNW_IA64_IP:
70 Contains the instruction pointer (IP, or ``program counter'')
71 of the current stack frame. Given this value, the remaining
72 machine-state corresponds to the register-values that were
73 present in the CPU when it was just about to execute the
74 instruction pointed to by UNW_IA64_IP. Bits 0 and 1 of this
75 frame-register encode the slot number of the instruction. Note:
76 Due to the way the call instruction works on IA-64, the slot
77 number is usually zero, but can be non-zero, e.g., in the
78 stack-frame of a signal-handler trampoline.
79 UNW_IA64_SP:
81 Contains the (memory) stack-pointer value (SP).
82 UNW_IA64_BSP:
84 Contains the register backing-store pointer (BSP). Note: the
85 value in this register is equal to the contents of register
86 ar.bsp at the time the instruction at UNW_IA64_IP was about to
87 begin execution.
88 NORMAL REGISTER MACROS
90 The following normal register name macros are available:
91 UNW_IA64_GR:
93 The base-index for general (integer) registers. Add an index in
94 the range from 0..127 to get a particular general register. For
95 example, to access r4, the index UNW_IA64_GR+4 should be used.
96 Registers r0 and r1 (gp) are read-only, and any attempt to write
97 them will result in an error (-UNW_EREADONLYREG). Even though
98 r1 is read-only, libunwind will automatically adjust its value
99 if the instruction-pointer (UNW_IA64_IP) is modified. For exam‐
100 ple, if UNW_IA64_IP is set to a value inside a function func(),
101 then reading UNW_IA64_GR+1 will return the global-pointer value
102 for this function.
103 UNW_IA64_NAT:
105 The base-index for the NaT bits of the general (integer) regis‐
106 ters. A non-zero value in these registers corresponds to a set
107 NaT-bit. Add an index in the range from 0..127 to get a particu‐
108 lar NaT-bit register. For example, to access the NaT bit of r4,
109 the index UNW_IA64_NAT+4 should be used.
110 UNW_IA64_FR:
112 The base-index for floating-point registers. Add an index in
113 the range from 0..127 to get a particular floating-point regis‐
114 ter. For example, to access f2, the index UNW_IA64_FR+2 should
115 be used. Registers f0 and f1 are read-only, and any attempt to
116 write to indices UNW_IA64_FR+0 or UNW_IA64_FR+1 will result in
117 an error (-UNW_EREADONLYREG).
118 UNW_IA64_AR:
120 The base-index for application registers. Add an index in the
121 range from 0..127 to get a particular application register. For
122 example, to access ar40, the index UNW_IA64_AR+40 should be
123 used. The IA-64 architecture defines several application regis‐
124 ters as ``reserved for future use''. Attempting to access such
125 registers results in an error (-UNW_EBADREG).
126 UNW_IA64_BR:
128 The base-index for branch registers. Add an index in the range
129 from 0..7 to get a particular branch register. For example, to
130 access b6, the index UNW_IA64_BR+6 should be used.
131 UNW_IA64_PR:
133 Contains the set of predicate registers. This 64-bit wide reg‐
134 ister contains registers p0 through p63 in the ``broad-side''
135 format. Just like with the ``move predicates'' instruction, the
136 registers are mapped as if CFM.rrb.pr were set to 0. Thus, in
137 general the value of predicate register pN with N>=16 can be
138 found in bit 16 + ((N-16)+CFM.rrb.pr) % 48.
139 UNW_IA64_CFM:
141 Contains the current-frame-mask register.
142 CONVENIENCE MACROS
144 Convenience macros are simply aliases for certain frequently used reg‐
145 isters:
146 UNW_IA64_GP:
148 Alias for UNW_IA64_GR+1, the global-pointer register.
149 UNW_IA64_TP:
151 Alias for UNW_IA64_GR+13, the thread-pointer register.
152 UNW_IA64_AR_RSC:
154 Alias for UNW_IA64_GR+16, the register-stack configuration reg‐
155 ister.
156 UNW_IA64_AR_BSP:
158 Alias for UNW_IA64_GR+17. This register index accesses the
159 value of register ar.bsp as of the time it was last saved
160 explicitly. This is rarely what you want. Normally, you'll want
161 to use UNW_IA64_BSP instead.
162 UNW_IA64_AR_BSPSTORE:
164 Alias for UNW_IA64_GR+18, the register-backing store write
165 pointer.
166 UNW_IA64_AR_RNAT:
168 Alias for UNW_IA64_GR+19, the register-backing store NaT-col‐
169 lection register.
170 UNW_IA64_AR_CCV:
172 Alias for UNW_IA64_GR+32, the compare-and-swap value register.
173 UNW_IA64_AR_CSD:
175 Alias for UNW_IA64_GR+25, the compare-and-swap-data register
176 (used by 16-byte atomic operations).
177 UNW_IA64_AR_UNAT:
179 Alias for UNW_IA64_GR+36, the user NaT-collection register.
180 UNW_IA64_AR_FPSR:
182 Alias for UNW_IA64_GR+40, the floating-point status (and con‐
183 trol) register.
184 UNW_IA64_AR_PFS:
186 Alias for UNW_IA64_GR+64, the previous frame-state register.
187 UNW_IA64_AR_LC:
189 Alias for UNW_IA64_GR+65 the loop-count register.
190 UNW_IA64_AR_EC:
192 Alias for UNW_IA64_GR+66, the epilogue-count register.
193
195 On IA-64, unw_context_t is simply an alias for ucontext_t (as defined
196 by the Single UNIX Spec). This implies that it is possible to initial‐
197 ize a value of this type not just with unw_getcontext(), but also with
198 getcontext(), for example. However, since this is an IA-64-specific
199 extension to libunwind, portable code should not rely on this equiva‐
200 lence.
201
203 libunwind(3)
204
206 David Mosberger-Tang
207 Hewlett-Packard Labs
208 Palo-Alto, CA 94304
209 Email: davidm@hpl.hp.com
210 WWW: http://www.hpl.hp.com/research/linux/libunwind/.
211Programming Library 20 May 2005 LIBUNWIND-IA64(3)