mirror of
https://github.com/tobast/libunwind-eh_elf.git
synced 2024-11-23 16:07:37 +01:00
313 lines
8.8 KiB
Groff
313 lines
8.8 KiB
Groff
'\" t
|
|
.\" Manual page created with latex2man on Mon Mar 31 14:18:01 PST 2003
|
|
.\" NOTE: This file is generated, DO NOT EDIT.
|
|
.de Vb
|
|
.ft CW
|
|
.nf
|
|
..
|
|
.de Ve
|
|
.ft R
|
|
|
|
.fi
|
|
..
|
|
.TH "LIBUNWIND\-IA64" "3" "31 March 2003" "Programming Library " "Programming Library "
|
|
.SH NAME
|
|
libunwind\-ia64
|
|
\-\- IA\-64\-specific support in libunwind
|
|
.PP
|
|
.SH INTRODUCTION
|
|
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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).
|
|
.PP
|
|
.SH MACHINE\-STATE
|
|
|
|
.PP
|
|
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 \fItry\fP
|
|
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\&.
|
|
.PP
|
|
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.
|
|
.PP
|
|
For a detailed description of the IA\-64 register usage convention,
|
|
please see the ``Itanium Software Conventions and Runtime Architecture
|
|
Guide\&'', available at:
|
|
.ce 100
|
|
\fBhttp://www.intel.com/design/itanium/downloads/245358.htm\fP
|
|
.ce 0
|
|
|
|
.PP
|
|
.SH REGISTER NAMES
|
|
|
|
.PP
|
|
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:
|
|
.PP
|
|
.SS FRAME\-REGISTER MACROS
|
|
.PP
|
|
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:
|
|
.TP
|
|
UNW_IA64_IP:
|
|
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.
|
|
\fBNote:\fP
|
|
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.
|
|
.TP
|
|
UNW_IA64_SP:
|
|
Contains the (memory) stack\-pointer
|
|
value (SP). This frame\-register is read\-only.
|
|
.TP
|
|
UNW_IA64_BSP:
|
|
Contains the register backing\-store
|
|
pointer (BSP). This frame\-register is read\-only. \fBNote:\fP
|
|
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.
|
|
.PP
|
|
.SS NORMAL REGISTER MACROS
|
|
.PP
|
|
The following normal register name macros are available:
|
|
.TP
|
|
UNW_IA64_GR:
|
|
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.
|
|
.TP
|
|
UNW_IA64_NAT:
|
|
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.
|
|
.TP
|
|
UNW_IA64_FR:
|
|
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).
|
|
.TP
|
|
UNW_IA64_AR:
|
|
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).
|
|
.TP
|
|
UNW_IA64_BR:
|
|
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.
|
|
.TP
|
|
UNW_IA64_PR:
|
|
Contains the set of predicate registers.
|
|
This 64\-bit wide register contains registers p0
|
|
through
|
|
p63
|
|
in the ``broad\-side\&'' format (i.e., p0
|
|
corresponds to bit 0, p1
|
|
to bit 1, and so on).
|
|
.TP
|
|
UNW_IA64_CFM:
|
|
Contains the current\-frame\-mask
|
|
register.
|
|
.PP
|
|
.SS CONVENIENCE MACROS
|
|
.PP
|
|
Convenience macros are simply aliases for certain frequently used
|
|
registers:
|
|
.TP
|
|
UNW_IA64_GP:
|
|
Alias for UNW_IA64_GR+1,
|
|
the global\-pointer register.
|
|
.TP
|
|
UNW_IA64_TP:
|
|
Alias for UNW_IA64_GR+13,
|
|
the thread\-pointer register.
|
|
.TP
|
|
UNW_IA64_AR_RSC:
|
|
Alias for UNW_IA64_GR+16,
|
|
the register\-stack configuration register.
|
|
.TP
|
|
UNW_IA64_AR_BSP:
|
|
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.
|
|
.TP
|
|
UNW_IA64_AR_BSPSTORE:
|
|
Alias for UNW_IA64_GR+18,
|
|
the register\-backing store write pointer.
|
|
.TP
|
|
UNW_IA64_AR_RNAT:
|
|
Alias for UNW_IA64_GR+19,
|
|
the register\-backing store NaT\-collection register.
|
|
.TP
|
|
UNW_IA64_AR_CCV:
|
|
Alias for UNW_IA64_GR+32,
|
|
the compare\-and\-swap value register.
|
|
.TP
|
|
UNW_IA64_AR_CSD:
|
|
Alias for UNW_IA64_GR+25,
|
|
the compare\-and\-swap\-data register (used by 16\-byte atomic operations).
|
|
.TP
|
|
UNW_IA64_AR_UNAT:
|
|
Alias for UNW_IA64_GR+36,
|
|
the user NaT\-collection register.
|
|
.TP
|
|
UNW_IA64_AR_FPSR:
|
|
Alias for UNW_IA64_GR+40,
|
|
the floating\-point status (and control) register.
|
|
.TP
|
|
UNW_IA64_AR_PFS:
|
|
Alias for UNW_IA64_GR+64,
|
|
the previous frame\-state register.
|
|
.TP
|
|
UNW_IA64_AR_LC:
|
|
Alias for UNW_IA64_GR+65
|
|
the loop\-count register.
|
|
.TP
|
|
UNW_IA64_AR_EC:
|
|
Alias for UNW_IA64_GR+66,
|
|
the epilogue\-count register.
|
|
.PP
|
|
.SH THE UNWIND\-CONTEXT TYPE
|
|
|
|
.PP
|
|
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.
|
|
.PP
|
|
.SH SEE ALSO
|
|
|
|
.PP
|
|
libunwind(3)
|
|
.PP
|
|
.SH AUTHOR
|
|
|
|
.PP
|
|
David Mosberger\-Tang
|
|
.br
|
|
Hewlett\-Packard Labs
|
|
.br
|
|
Palo\-Alto, CA 94304
|
|
.br
|
|
Email: \fBdavidm@hpl.hp.com\fP
|
|
.br
|
|
WWW: \fBhttp://www.hpl.hp.com/research/linux/libunwind/\fP\&.
|
|
.\" NOTE: This file is generated, DO NOT EDIT.
|