Man Linux: Main Page and Category List


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


       The  IA-64  version of libunwind uses a platform-string of ia64 and, at
       least in theory, should  be  able  to  support  all  operating  systems
       adhering   to  the  processor-specific  ABI  defined  for  the  Itanium
       Processor Family. This includes both little-endian Linux and big-endian
       HP-UX.  Furthermore, to make it possible for a single library to unwind
       both 32- and 64-bit targets, the type unw_word_t is always  defined  to
       be  64  bits  wide  (independent of the natural word-size of the host).
       Having said that, the current implementation has been tested only  with
       IA-64 Linux.

       When  targeting  IA-64,  the  libunwind  header  file defines the macro
       UNW_TARGET_IA64 as 1 and the macro UNW_TARGET as ``ia64'' (without  the
       quotation  marks).  The former makes it possible for platform-dependent
       unwind code to use conditional-compilation  to  select  an  appropriate
       implementation.  The  latter is useful for stringification purposes and
       to construct target-platform-specific symbols.

       One special feature of  IA-64  is  the  use  of  NaT  bits  to  support
       speculative  execution.  Often,  NaT bits are thought of as the ``65-th
       bit'' of a general register.  However,  to  make  everything  fit  into
       64-bit  wide  unw_word_t  values,  libunwind  treats  the NaT-bits like
       separate  boolean  registers,  whose  64-bit  value  is   either   TRUE
       (non-zero) or FALSE (zero).


       The  machine-state  (set  of  registers)  that  is  accessible  through
       libunwind depends on the type of stack frame that a cursor  points  to.
       For  normal  frames,  all  ``preserved''  (callee-saved)  registers are
       accessible. For  signal-trampoline  frames,  all  registers  (including
       ``scratch'' (caller-saved) registers) are accessible. Most applications
       do not have to worry a-priori  about  which  registers  are  accessible
       when.  In  case of doubt, it is always safe to try to access a register
       (via unw_get_reg()  or  unw_get_fpreg())  and  if  the  register  isn't
       accessible, the call will fail with a return-value of -UNW_EBADREG.

       As  a  special  exception  to the above general rule, scratch registers
       r15-r18 are always accessible, even in normal  frames.  This  makes  it
       possible to pass arguments, e.g., to exception handlers.

       For  a  detailed  description  of  the IA-64 register usage convention,
       please see the ``Itanium Software Conventions and Runtime  Architecture
       Guide'', available at:


       The  IA-64-version  of  libunwind  defines three kinds of register name
       macros: frame-register macros, normal register macros, and  convenience
       macros. Below, we describe each kind in turn:

       Frame-registers are special (pseudo) registers because they always have
       a valid value, even though sometimes they do not get  saved  explicitly
       (e.g.,  if  a  memory  stack  frame  is  16 bytes in size, the previous
       stack-pointer value can be calculated simply as sp+16, so there  is  no
       need  to save the stack-pointer explicitly). Moreover, the set of frame
       register  values  uniquely  identifies  a  stack   frame.   The   IA-64
       architecture  defines  two  stacks  (a  memory  and  a register stack).
       Including the instruction-pointer (IP),  this  means  there  are  three
       frame registers:

               Contains  the  instruction pointer (IP, or ``program counter'')
              of the current stack frame.  Given  this  value,  the  remaining
              machine-state  corresponds  to  the  register-values  that  were
              present in the CPU  when  it  was  just  about  to  execute  the
              instruction  pointed  to  by  UNW_IA64_IP.  Bits 0 and 1 of this
              frame-register encode the slot number of the instruction.  Note:
              Due  to  the  way  the call instruction works on IA-64, the slot
              number is usually zero,  but  can  be  non-zero,  e.g.,  in  the
              stack-frame of a signal-handler trampoline.

               Contains the (memory) stack-pointer value (SP).

               Contains  the  register  backing-store pointer (BSP). Note: the
              value in this register is equal  to  the  contents  of  register
              ar.bsp  at  the time the instruction at UNW_IA64_IP was about to
              begin execution.

       The following normal register name macros are available:

               The base-index for general (integer) registers. Add an index in
              the  range from 0..127 to get a particular general register. For
              example, to access r4, the index UNW_IA64_GR+4 should  be  used.
              Registers r0 and r1 (gp) are read-only, and any attempt to write
              them will result in an error (-UNW_EREADONLYREG).   Even  though
              r1  is  read-only, libunwind will automatically adjust its value
              if  the  instruction-pointer  (UNW_IA64_IP)  is  modified.   For
              example,  if  UNW_IA64_IP  is  set  to a value inside a function
              func(),   then   reading   UNW_IA64_GR+1   will    return    the
              global-pointer value for this function.

               The  base-index  for  the  NaT  bits  of  the general (integer)
              registers. A non-zero value in these registers corresponds to  a
              set  NaT-bit.  Add  an  index  in the range from 0..127 to get a
              particular NaT-bit register. For example, to access the NaT  bit
              of r4, the index UNW_IA64_NAT+4 should be used.

               The  base-index  for  floating-point registers. Add an index in
              the  range  from  0..127  to  get  a  particular  floating-point
              register.  For  example,  to  access f2, the index UNW_IA64_FR+2
              should be used. Registers f0  and  f1  are  read-only,  and  any
              attempt  to write to indices UNW_IA64_FR+0 or UNW_IA64_FR+1 will
              result in an error (-UNW_EREADONLYREG).

               The base-index for application registers. Add an index  in  the
              range  from 0..127 to get a particular application register. For
              example, to access ar40,  the  index  UNW_IA64_AR+40  should  be
              used.   The   IA-64  architecture  defines  several  application
              registers as ``reserved for future use''. Attempting  to  access
              such registers results in an error (-UNW_EBADREG).

               The base-index for branch registers.  Add an index in the range
              from 0..7 to get a particular branch register. For  example,  to
              access b6, the index UNW_IA64_BR+6 should be used.

               Contains  the  set  of  predicate  registers.  This 64-bit wide
              register contains registers p0 through p63 in the ``broad-side''
              format.  Just like with the ``move predicates'' instruction, the
              registers are mapped as if were set to  0.  Thus,  in
              general  the  value  of  predicate register pN with N>=16 can be
              found in bit 16 + ((N-16) % 48.

               Contains the current-frame-mask register.

       Convenience macros are  simply  aliases  for  certain  frequently  used

               Alias for UNW_IA64_GR+1, the global-pointer register.

               Alias for UNW_IA64_GR+13, the thread-pointer register.

               Alias  for  UNW_IA64_GR+16,  the  register-stack  configuration

               Alias for UNW_IA64_GR+17.  This  register  index  accesses  the
              value  of  register  ar.bsp  as  of  the  time it was last saved
              explicitly. This is rarely what you want. Normally, you'll  want
              to use UNW_IA64_BSP instead.

               Alias  for  UNW_IA64_GR+18,  the  register-backing  store write

               Alias   for   UNW_IA64_GR+19,   the   register-backing    store
              NaT-collection register.

               Alias  for UNW_IA64_GR+32, the compare-and-swap value register.

               Alias for UNW_IA64_GR+25,  the  compare-and-swap-data  register
              (used by 16-byte atomic operations).

               Alias for UNW_IA64_GR+36, the user NaT-collection register.

               Alias   for  UNW_IA64_GR+40,  the  floating-point  status  (and
              control) register.

               Alias for UNW_IA64_GR+64, the previous frame-state register.

               Alias for UNW_IA64_GR+65 the loop-count register.

               Alias for UNW_IA64_GR+66, the epilogue-count register.


       On IA-64, unw_context_t is simply an alias for ucontext_t  (as  defined
       by  the  Single  UNIX  Spec).  This  implies  that  it  is  possible to
       initialize a value of this type not  just  with  unw_getcontext(),  but
       also  with  getcontext(),  for  example.  However,  since  this  is  an
       IA-64-specific extension to libunwind, portable code should not rely on
       this equivalence.




       David Mosberger-Tang