doc/libunwind-ia64.man

   1 '\" t
   2 .\" Manual page created with latex2man on Thu Aug 16 09:44:44 MDT 2007
   3 .\" NOTE: This file is generated, DO NOT EDIT.
   4 .de Vb
   5 .ft CW
   6 .nf
   7 ..
   8 .de Ve
   9 .ft R
  10
  11 .fi
  12 ..
  13 .TH "LIBUNWIND\-IA64" "3" "16 August 2007" "Programming Library " "Programming Library "
  14 .SH NAME
  15 libunwind\-ia64
  16 \-\- IA\-64\-specific support in libunwind
  17 .PP
  18 .SH INTRODUCTION
  19
  20 .PP
  21 The IA\-64 version of libunwind
  22 uses a platform\-string of
  23 ia64
  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
  29 unw_word_t
  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.
  33 .PP
  34 When targeting IA\-64, the libunwind
  35 header file defines the
  36 macro UNW_TARGET_IA64
  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.
  43 .PP
  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
  48 values, libunwind
  49 treats the
  50 NaT\-bits like separate boolean registers, whose 64\-bit value is either
  51 TRUE (non\-zero) or FALSE (zero).
  52 .PP
  53 .SH MACHINE\-STATE
  54
  55 .PP
  56 The machine\-state (set of registers) that is accessible through
  57 libunwind
  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
  64 to
  65 access a register (via unw_get_reg()
  66 or
  67 unw_get_fpreg())
  68 and if the register isn\&'t accessible, the
  69 call will fail with a return\-value of \-UNW_EBADREG\&.
  70 .PP
  71 As a special exception to the above general rule, scratch registers
  72 r15\-r18
  73 are always accessible, even in normal
  74 frames. This makes it possible to pass arguments, e.g., to exception
  75 handlers.
  76 .PP
  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:
  80 .ce 100
  81 \fBhttp://www.intel.com/design/itanium/downloads/245358.htm\fP
  82 .ce 0
  83
  84 .PP
  85 .SH REGISTER NAMES
  86
  87 .PP
  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:
  92 .PP
  93 .SS FRAME\-REGISTER MACROS
  94 .PP
  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
  99 sp+16,
 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:
 105 .TP
 106 UNW_IA64_IP:
 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\&.
 112 Bits 0 and 1 of
 113 this frame\-register encode the slot number of the instruction.
 114 \fBNote:\fP
 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.
 118 .TP
 119 UNW_IA64_SP:
 120  Contains the (memory) stack\-pointer
 121 value (SP).
 122 .TP
 123 UNW_IA64_BSP:
 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
 128 at the time the
 129 instruction at UNW_IA64_IP
 130 was about to begin execution.
 131 .PP
 132 .SS NORMAL REGISTER MACROS
 133 .PP
 134 The following normal register name macros are available:
 135 .TP
 136 UNW_IA64_GR:
 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
 141 should be used.
 142 Registers r0
 143 and r1
 144 (gp)
 145 are read\-only,
 146 and any attempt to write them will result in an error
 147 (\-UNW_EREADONLYREG).
 148 Even though r1
 149 is
 150 read\-only, libunwind
 151 will automatically adjust its value if
 152 the instruction\-pointer (UNW_IA64_IP)
 153 is modified. For
 154 example, if UNW_IA64_IP
 155 is set to a value inside a
 156 function func(),
 157 then reading
 158 UNW_IA64_GR+1
 159 will return the global\-pointer
 160 value for this function.
 161 .TP
 162 UNW_IA64_NAT:
 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
 167 NaT bit of r4,
 168 the index UNW_IA64_NAT+4
 169 should be used.
 170 .TP
 171 UNW_IA64_FR:
 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
 175 f2,
 176 the index UNW_IA64_FR+2
 177 should be
 178 used. Registers f0
 179 and f1
 180 are read\-only, and any
 181 attempt to write to indices UNW_IA64_FR+0
 182 or
 183 UNW_IA64_FR+1
 184 will result in an error
 185 (\-UNW_EREADONLYREG).
 186 .TP
 187 UNW_IA64_AR:
 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
 191 ar40,
 192 the index UNW_IA64_AR+40
 193 should be
 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).
 197 .TP
 198 UNW_IA64_BR:
 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,
 202 the index
 203 UNW_IA64_BR+6
 204 should be used.
 205 .TP
 206 UNW_IA64_PR:
 207  Contains the set of predicate registers.
 208 This 64\-bit wide register contains registers p0
 209 through
 210 p63
 211 in the ``broad\-side\&'' format. Just like with the
 212 ``move predicates\&'' instruction, the registers are mapped as if
 213 CFM.rrb.pr
 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\&.
 218 .TP
 219 UNW_IA64_CFM:
 220  Contains the current\-frame\-mask
 221 register.
 222 .PP
 223 .SS CONVENIENCE MACROS
 224 .PP
 225 Convenience macros are simply aliases for certain frequently used
 226 registers:
 227 .TP
 228 UNW_IA64_GP:
 229  Alias for UNW_IA64_GR+1,
 230 the global\-pointer register.
 231 .TP
 232 UNW_IA64_TP:
 233  Alias for UNW_IA64_GR+13,
 234 the thread\-pointer register.
 235 .TP
 236 UNW_IA64_AR_RSC:
 237  Alias for UNW_IA64_GR+16,
 238 the register\-stack configuration register.
 239 .TP
 240 UNW_IA64_AR_BSP:
 241  Alias for
 242 UNW_IA64_GR+17\&.
 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
 247 use UNW_IA64_BSP
 248 instead.
 249 .TP
 250 UNW_IA64_AR_BSPSTORE:
 251  Alias for UNW_IA64_GR+18,
 252 the register\-backing store write pointer.
 253 .TP
 254 UNW_IA64_AR_RNAT:
 255  Alias for UNW_IA64_GR+19,
 256 the register\-backing store NaT\-collection register.
 257 .TP
 258 UNW_IA64_AR_CCV:
 259  Alias for UNW_IA64_GR+32,
 260 the compare\-and\-swap value register.
 261 .TP
 262 UNW_IA64_AR_CSD:
 263  Alias for UNW_IA64_GR+25,
 264 the compare\-and\-swap\-data register (used by 16\-byte atomic operations).
 265 .TP
 266 UNW_IA64_AR_UNAT:
 267  Alias for UNW_IA64_GR+36,
 268 the user NaT\-collection register.
 269 .TP
 270 UNW_IA64_AR_FPSR:
 271  Alias for UNW_IA64_GR+40,
 272 the floating\-point status (and control) register.
 273 .TP
 274 UNW_IA64_AR_PFS:
 275  Alias for UNW_IA64_GR+64,
 276 the previous frame\-state register.
 277 .TP
 278 UNW_IA64_AR_LC:
 279  Alias for UNW_IA64_GR+65
 280 the loop\-count register.
 281 .TP
 282 UNW_IA64_AR_EC:
 283  Alias for UNW_IA64_GR+66,
 284 the epilogue\-count register.
 285 .PP
 286 .SH THE UNWIND\-CONTEXT TYPE
 287
 288 .PP
 289 On IA\-64, unw_context_t
 290 is simply an alias for
 291 ucontext_t
 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
 294 unw_getcontext(),
 295 but also with getcontext(),
 296 for
 297 example. However, since this is an IA\-64\-specific extension to
 298 libunwind,
 299 portable code should not rely on this equivalence.
 300 .PP
 301 .SH SEE ALSO
 302
 303 .PP
 304 libunwind(3)
 305 .PP
 306 .SH AUTHOR
 307
 308 .PP
 309 David Mosberger\-Tang
 310 .br
 311 Email: \fBdmosberger@gmail.com\fP
 312 .br
 313 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
 314 .\" NOTE: This file is generated, DO NOT EDIT.