1LIBUNWIND-IA64(3)            Programming Library             LIBUNWIND-IA64(3)
2
3
4

NAME

6       libunwind-ia64 -- IA-64-specific support in libunwind
7

INTRODUCTION

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
19       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
26       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

MACHINE-STATE

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
44       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
48       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
53

REGISTER NAMES

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
59   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
69       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
80       UNW_IA64_SP:
81               Contains the (memory) stack-pointer value (SP).
82
83       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
89   NORMAL REGISTER MACROS
90       The following normal register name macros are available:
91
92       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
104       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
111       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
119       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
127       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
132       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
140       UNW_IA64_CFM:
141               Contains the current-frame-mask register.
142
143   CONVENIENCE MACROS
144       Convenience  macros are simply aliases for certain frequently used reg‐
145       isters:
146
147       UNW_IA64_GP:
148               Alias for UNW_IA64_GR+1, the global-pointer register.
149
150       UNW_IA64_TP:
151               Alias for UNW_IA64_GR+13, the thread-pointer register.
152
153       UNW_IA64_AR_RSC:
154               Alias for UNW_IA64_GR+16, the register-stack configuration reg‐
155              ister.
156
157       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
163       UNW_IA64_AR_BSPSTORE:
164               Alias for  UNW_IA64_GR+18,  the  register-backing  store  write
165              pointer.
166
167       UNW_IA64_AR_RNAT:
168               Alias  for  UNW_IA64_GR+19, the register-backing store NaT-col‐
169              lection register.
170
171       UNW_IA64_AR_CCV:
172               Alias for UNW_IA64_GR+32, the compare-and-swap value register.
173
174       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
178       UNW_IA64_AR_UNAT:
179               Alias for UNW_IA64_GR+36, the user NaT-collection register.
180
181       UNW_IA64_AR_FPSR:
182               Alias  for  UNW_IA64_GR+40, the floating-point status (and con‐
183              trol) register.
184
185       UNW_IA64_AR_PFS:
186               Alias for UNW_IA64_GR+64, the previous frame-state register.
187
188       UNW_IA64_AR_LC:
189               Alias for UNW_IA64_GR+65 the loop-count register.
190
191       UNW_IA64_AR_EC:
192               Alias for UNW_IA64_GR+66, the epilogue-count register.
193

THE UNWIND-CONTEXT TYPE

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

SEE ALSO

203       libunwind(3)
204

AUTHOR

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/.
211
212
213
214Programming Library               20 May 2005                LIBUNWIND-IA64(3)
Impressum