libraries.tex

\chapter{Libraries}

A further review of the \intelabi is needed.

\section{C Library}

\subsection{Global Data Symbols}

The symbols \code{_fp_hw}, \code{__flt_rounds} and \code{__huge_val}
are not provided by the \xARCH ABI.

\subsection{Floating Point Environment Functions}

ISO C 99 defines the floating point environment functions from
\code{<fenv.h>}.  Since \xARCH has two floating point units with
separate control words, the programming environment has to keep the
control values in sync.  On the other hand this means that routines
accessing the control words only need to access one unit, and the SSE
unit is the unit that should be accessed in these cases.  The
function \codeindex{fegetround} therefore only needs to report the
rounding value of the SSE unit and can ignore the x87 unit.

\section{Unwind Library Interface\label{unwindlib}}

This section defines the \textindex{Unwind Library interface}%
\footnote{The overall structure and the external interface is derived
from the IA-64 UNIX System V ABI},
expected to be provided by any \xARCH psABI-compliant system.
This is the interface on which the C++ ABI exception-handling
facilities are built. We assume as a basis the
\textindex{Call Frame Information tables} described in the
\textindex{DWARF Debugging Information Format} document.

This section is meant to specify a language-independent interface that
can be used to provide higher level exception-handling facilities such
as those defined by C++.

The unwind library interface consists of at least the following routines:\\
\codeindex{\_Unwind\_RaiseException},\\
\codeindex{\_Unwind\_Resume},\\
\codeindex{\_Unwind\_DeleteException},\\
\codeindex{\_Unwind\_GetGR},\\
\codeindex{\_Unwind\_SetGR},\\
\codeindex{\_Unwind\_GetIP},\\
\codeindex{\_Unwind\_GetIPInfo},\\
\codeindex{\_Unwind\_SetIP},\\
\codeindex{\_Unwind\_GetRegionStart},\\
\codeindex{\_Unwind\_GetLanguageSpecificData},\\
\codeindex{\_Unwind\_ForcedUnwind},\\
\codeindex{\_Unwind\_GetCFA}

\begin{sloppypar}
In addition, two data types are defined (\codeindex{\_Unwind\_Context}
and \codeindex{\_Unwind\_Exception}) to interface a calling runtime
(such as the C++ runtime) and the above routine. All routines and
interfaces behave as if defined \texttt{extern "C"}. In particular,
the names are not mangled. All names defined as part of this interface
have a \texttt{"\_Unwind\_"} prefix.
\end{sloppypar}

Lastly, a language and vendor specific personality routine will be
stored by the compiler in the unwind descriptor for the stack frames
requiring exception processing. The personality routine is called by
the unwinder to handle language-specific tasks such as identifying the
frame handling a particular exception.

\subsection{Exception Handler Framework}

\subsubsection{Reasons for Unwinding}
There are two major reasons for unwinding the stack:
\begin{itemize}
  \item exceptions, as defined by languages that support them (such as C++)
  \item ``forced'' unwinding (such as caused by \codeindex{longjmp} or thread
    termination)
\end{itemize}

The interface described here tries to keep both similar. There is a
major difference, however.
\begin{itemize}

\item In the case where an exception is thrown, the stack is unwound
while the exception propagates, but it is expected that the personality
routine for each stack frame knows whether it wants to catch the exception
or pass it through. This choice is thus delegated to the personality
routine, which is expected to act properly for any type of exception,
whether ``native'' or ``foreign''.  Some guidelines for ``acting properly''
are given below.

\item During ``forced unwinding'', on the other hand, an external agent is
driving the unwinding. For instance, this can be the \texttt{longjmp}
routine. This external agent, not each personality routine,
knows when to stop unwinding. The fact that a personality routine is
not given a choice about whether unwinding will proceed is indicated by the
\codeindex{\_UA\_FORCE\_UNWIND} flag.
\end{itemize}

\begin{sloppypar}
To accommodate these differences, two different routines are proposed.
\codeindex{\_Unwind\_RaiseException} performs exception-style unwinding,
under control of the personality routines. \codeindex{\_Unwind\_ForcedUnwind},
on the other hand, performs unwinding, but gives an external agent the
opportunity to intercept calls to the personality routine. This is done using
a proxy personality routine, that intercepts calls to the personality routine,
letting the external agent override the defaults of the stack frame's
personality routine.
\end{sloppypar}

As a consequence, it is not necessary for each personality routine to know
about any of the possible external agents that may cause an unwind. For
instance, the C++ personality routine need deal only with C++ exceptions
(and possibly disguising foreign exceptions), but it does not need to know
anything specific about unwinding done on behalf of \texttt{longjmp} or
pthreads cancellation.

\subsubsection{The Unwind Process}

The standard ABI exception handling/unwind process begins with the raising
of an exception, in one of the forms mentioned above. This call specifies an
exception object and an exception class.

The runtime framework then starts a two-phase process:
\begin{itemize}
\item In the \emph{search} phase, the framework repeatedly calls the
personality routine, with the \codeindex{\_UA\_SEARCH\_PHASE} flag as
described below, first for the current \RIP and register state, and then
unwinding a frame to a new \RIP at each step, until the personality
routine reports either success (a handler found in the queried frame)
or failure (no handler) in all frames. It does not actually restore the
unwound state, and the personality routine must access the state through
the API.

\item If the search phase reports a failure, e.g. because no handler was
found, it will call \codeindex{terminate()} rather than commence phase 2.

\begin{sloppypar}
If the search phase reports success, the framework restarts in the
\emph{cleanup} phase. Again, it repeatedly calls the personality
routine, with the \codeindex{\_UA\_CLEANUP\_PHASE} flag as described
below, first for the current \RIP and register state, and then unwinding
a frame to a new \RIP at each step, until it gets to the frame with
an identified handler. At that point, it restores the register state,
and control is transferred to the user landing pad code.
\end{sloppypar}
\end {itemize}

Each of these two phases uses both the unwind library and the personality
routines, since the validity of a given handler and the mechanism for
transferring control to it are language-dependent, but the method of
locating and restoring previous stack frames is language-independent.

A two-phase exception-handling model is not strictly necessary to
implement C++ language semantics, but it does provide some benefits. For
example, the first phase allows an exception-handling mechanism to
\emph{dismiss} an exception before stack unwinding begins, which allows
\emph{presumptive} exception handling (correcting the exceptional condition
and resuming execution at the point where it was raised). While C++ does
not support presumptive exception handling, other languages do, and the
two-phase model allows C++ to coexist with those languages on the stack.

Note that even with a two-phase model, we may execute each of the two
phases more than once for a single exception, as if the exception was
being thrown more than once. For instance, since it is not possible to
determine if a given catch clause will re-throw or not without executing
it, the exception propagation effectively stops at each catch clause,
and if it needs to restart, restarts at phase 1. This process is not
needed for destructors (cleanup code), so the phase 1 can safely process
all destructor-only frames at once and stop at the next enclosing
catch clause.

For example, if the first two frames unwound contain only cleanup code,
and the third frame contains a C++ catch clause, the personality routine
in phase 1, does not indicate that it found a handler for the first two
frames. It must do so for the third frame, because it is unknown how the
exception will propagate out of this third frame, e.g. by re-throwing the
exception or throwing a new one in C++.

The API specified by the \xARCH psABI for implementing this framework
is described in the following sections.

\subsection{Data Structures}

\subsubsection{Reason Codes}

The unwind interface uses reason codes in several contexts to identify the
reasons for failures or other actions, defined as follows:

\code{
\begin{tabular}{l}
    typedef enum \{\\
    \ \ \ \_URC\_NO\_REASON = 0,\\
    \ \ \ \_URC\_FOREIGN\_EXCEPTION\_CAUGHT = 1,\\
    \ \ \ \_URC\_FATAL\_PHASE2\_ERROR = 2,\\
    \ \ \ \_URC\_FATAL\_PHASE1\_ERROR = 3,\\
    \ \ \ \_URC\_NORMAL\_STOP = 4,\\
    \ \ \ \_URC\_END\_OF\_STACK = 5,\\
    \ \ \ \_URC\_HANDLER\_FOUND = 6,\\
    \ \ \ \_URC\_INSTALL\_CONTEXT = 7,\\
    \ \ \ \_URC\_CONTINUE\_UNWIND = 8\\
    \} \_Unwind\_Reason\_Code;\\
\end{tabular}
}

The interpretations of these codes are described below.

\subsubsection{Exception Header}

The unwind interface uses a pointer to an exception header object
as its representation of an exception being thrown. In general,
the full representation of an exception object is language- and
implementation-specific, but is prefixed by a header understood
by the unwind interface, defined as follows:

\code{
\begin{tabular}{l}
    typedef void (*\_Unwind\_Exception\_Cleanup\_Fn)\\
    \ \ (\_Unwind\_Reason\_Code reason,\\
    \ \ \ struct \_Unwind\_Exception *exc);\\
\end{tabular}
}

\code{
\begin{tabular}{ll}
    struct \_Unwind\_Exception \{\\
    \ \ \ uint64 & exception\_class;\\
    \ \ \ \_Unwind\_Exception\_Cleanup\_Fn & exception\_cleanup;\\
    \ \ \ uint64 & private\_1;\\
    \ \ \ uint64 & private\_2;\\
    \};\\
\end{tabular}
}

An \code{\_Unwind\_Exception} object must be \eightbyte aligned.  The first
two fields are set by user code prior to raising the exception, and the
latter two should never be touched except by the runtime.

The \code{exception\_class} field is a language- and implementation-specific
identifier of the kind of exception. It allows a personality routine
to distinguish between native and foreign exceptions, for example.
By convention, the high 4 bytes indicate the vendor (for instance
AMD$\backslash$0), and the low 4 bytes indicate the language.  For the C++
ABI described in this document, the low four bytes are C++$\backslash$0.

The \code{exception\_cleanup} routine is called whenever an exception object
needs to be destroyed by a different runtime than the runtime
which created the exception object, for instance if a Java exception
is caught by a C++ catch handler. In such a case, a reason code (see
above) indicates why the exception object needs to be deleted:

\begin{description}
\item[\code{\_URC\_FOREIGN\_EXCEPTION\_CAUGHT = 1}] This indicates that a
     different runtime caught this exception. Nested foreign exceptions,
     or re-throwing a foreign exception, result in undefined behavior.

\item[\code{\_URC\_FATAL\_PHASE1\_ERROR = 3}] The personality routine encountered
     an error during phase 1, other than the specific error codes defined.

\item[\code{\_URC\_FATAL\_PHASE2\_ERROR = 2}] The personality routine
  encountered an error during phase 2, for instance a stack corruption.
\end{description}

Normally, all errors should be reported during phase 1 by returning
from \code{\_Unwind\_RaiseException}. However, landing pad code could cause
stack corruption between phase 1 and phase 2. For a C++ exception,
the runtime should call \code{terminate()} in that case.

The private unwinder state (\code{private\_1} and \code{private\_2}) in an exception
object should be neither read by nor written to by personality routines or
other parts of the language-specific runtime.  It is used by the specific
implementation of the unwinder on the host to store internal information,
for instance to remember the final handler frame between unwinding phases.

In addition to the above information, a typical runtime such as the
C++ runtime will add language-specific information used to process the
exception.  This is expected to be a contiguous area of memory after
the \code{\_Unwind\_Exception} object, but this is not required as
long as the matching personality routines know how to deal with it,
and the \code{exception\_cleanup} routine de-allocates it properly.

\subsubsection{Unwind Context}

The \code{\_Unwind\_Context} type is an opaque type used to refer to a
system-specific data structure used by the system unwinder.  This context
is created and destroyed by the system, and passed to the personality
routine during unwinding.

\code{
struct \_Unwind\_Context\\
}

\subsection{Throwing an Exception}

\subsubsection{\code{\_Unwind\_RaiseException}}

\code{
\begin{tabular}{l}
   \_Unwind\_Reason\_Code \_Unwind\_RaiseException\\
   \ \ ( struct \_Unwind\_Exception *exception\_object );\\
\end{tabular}
}

Raise an exception, passing along the given exception object,
which should have its \code{exception\_class} and \code{exception\_cleanup} fields
set. The exception object has been allocated by the language-specific
runtime, and has a language-specific format, except that it must
contain an \code{\_Unwind\_Exception} struct (see Exception Header above).
\code{\_Unwind\_RaiseException} does not return, unless an error condition is
found (such as no handler for the exception, bad stack format, etc.).
In such a case, an \code{\_Unwind\_Reason\_Code} value is returned.

Possibilities are:
\begin{description}
\item[\code{\_URC\_END\_OF\_STACK}]
\begin{sloppypar}
    The unwinder encountered the end of the
   stack during phase 1, without finding a handler. The unwind runtime
   will not have modified the stack. The C++ runtime will normally call
   \code{uncaught\_exception()} in this case.
\end{sloppypar}
\item[\code{\_URC\_FATAL\_PHASE1\_ERROR}] The unwinder encountered an unexpected
   error during phase 1, e.g. stack corruption. The unwind runtime will
   not have modified the stack. The C++ runtime will normally call
   \code{terminate()} in this case.
\end{description}

If the unwinder encounters an unexpected error during phase 2, it
should return \code{\_URC\_FATAL\_PHASE2\_ERROR} to its caller.  In
C++, this will usually be \code{\_\_cxa\_throw}, which will call
\code{terminate()}.

The unwind runtime will likely have modified the stack (e.g. popped
frames from it) or register context, or landing pad code may have
corrupted them. As a result, the the caller of \code{\_Unwind\_RaiseException}
can make no assumptions about the state of its stack or registers.

\subsubsection{\code{\_Unwind\_ForcedUnwind}}

\code{
\begin{tabular}{l}
   typedef \_Unwind\_Reason\_Code (*\_Unwind\_Stop\_Fn)\\
   \ \ (int version,\\
   \ \ \ \_Unwind\_Action actions,\\
   \ \ \ uint64 exceptionClass,\\
   \ \ \ struct \_Unwind\_Exception *exceptionObject,\\
   \ \ \ struct \_Unwind\_Context *context,\\
   \ \ \ void *stop\_parameter );\\
\end{tabular}
}

\code{
\begin{tabular}{l}
   \_Unwind\_Reason\_Code\_Unwind\_ForcedUnwind\\
   \ \ ( struct \_Unwind\_Exception *exception\_object,\\
   \ \ \ \_Unwind\_Stop\_Fn stop,\\
   \ \ \ void *stop\_parameter );\\
\end{tabular}
}

\begin{sloppypar}
Raise an exception for forced unwinding, passing along the given
exception object, which should have its \code{exception\_class} and
\code{exception\_cleanup} fields set. The exception object has been allocated
by the language-specific runtime, and has a language-specific format,
except that it must contain an \code{\_Unwind\_Exception} struct (see Exception
Header above).
\end{sloppypar}

Forced unwinding is a single-phase process (phase 2 of the normal
exception-handling process). The \code{stop} and
\code{stop\_parameter} parameters control the termination of the
unwind process, instead of the usual personality routine query. The
\code{stop} function parameter is called for each unwind frame, with
the parameters described for the usual personality routine below, plus
an additional \code{stop\_parameter}.

When the \code{stop} function identifies the destination frame, it
transfers control (according to its own, unspecified, conventions)
to the user code as appropriate without returning, normally after
calling \code{\_Unwind\_DeleteException}. If not, it should return an
\code{\_Unwind\_Reason\_Code} value as follows:

\begin{description}
\item[\code{\_URC\_NO\_REASON}]
     This is not the destination frame. The unwind
     runtime will call the frame's personality routine with the
     \code{\_UA\_FORCE\_UNWIND} and \code{\_UA\_CLEANUP\_PHASE} flags set in actions,
     and then unwind to the next frame and call the stop function again.

\item[\code{\_URC\_END\_OF\_STACK}] In order to allow \code{\_Unwind\_ForcedUnwind}
     to perform special processing when it reaches the end of the stack,
     the unwind runtime will call it after the last frame is rejected,
     with a \code{NULL} stack pointer in the context, and the stop function must
     catch this condition (i.e. by noticing the \code{NULL} stack pointer).
     It may return this reason code if it cannot handle end-of-stack.

\item[\code{\_URC\_FATAL\_PHASE2\_ERROR}] The stop function may return this code
     for other fatal conditions, e.g. stack corruption.
\end{description}

\begin{sloppypar}
If the stop function returns any reason code other than \code{\_URC\_NO\_REASON},
the stack state is indeterminate from the point of view of the caller of
\code{\_Unwind\_ForcedUnwind}. Rather than attempt to return, therefore,
the unwind library should return \code{\_URC\_FATAL\_PHASE2\_ERROR} to its caller.
\end{sloppypar}

\paragraph{Example: \code{longjmp\_unwind()}\\}

\begin{sloppypar}
The expected implementation of \code{longjmp\_unwind()} is as follows.
The \code{setjmp()} routine will have saved the state to be restored in its
customary place, including the frame pointer. The \code{longjmp\_unwind()}
routine will call \code{\_Unwind\_ForcedUnwind} with a stop function that
compares the frame pointer in the context record with the saved frame
pointer. If equal, it will restore the \code{setjmp()} state as customary,
and otherwise it will return \code{\_URC\_NO\_REASON} or \code{\_URC\_END\_OF\_STACK}.
\end{sloppypar}

If a future requirement for two-phase forced unwinding were identified,
an alternate routine could be defined to request it, and an actions
parameter flag defined to support it.

\subsubsection{\code{\_Unwind\_Resume}}

\code{
\begin{tabular}{l}
    void \_Unwind\_Resume\\
    \ \ (struct \_Unwind\_Exception *exception\_object);\\
\end{tabular}
}

Resume propagation of an existing exception e.g. after executing cleanup
code in a partially unwound stack. A call to this routine is inserted
at the end of a landing pad that performed cleanup, but did not resume
normal execution. It causes unwinding to proceed further.

\code{\_Unwind\_Resume} should not be used to implement re-throwing.
To the unwinding runtime, the catch code that re-throws was a handler,
and the previous unwinding session was terminated before entering it.
Re-throwing is implemented by calling \code{\_Unwind\_RaiseException}
again with the same exception object.

This is the only routine in the unwind library which is expected
to be called directly by generated code: it will be called at the
end of a landing pad in a "landing-pad" model.

\subsection{Exception Object Management}

\subsubsection{\code{\_Unwind\_DeleteException}}

\code{
\begin{tabular}{l}
    void \_Unwind\_DeleteException\\
    \ \ (struct \_Unwind\_Exception *exception\_object);\\
\end{tabular}
}

\begin{sloppypar}
Deletes the given exception object. If a given runtime resumes normal
execution after catching a foreign exception, it will not know how to
delete that exception. Such an exception will be deleted by calling
\code{\_Unwind\_DeleteException}. This is a convenience function that calls
the function pointed to by the \code{exception\_cleanup} field of the exception
header.
\end{sloppypar}

\subsection{Context Management}

These functions are used for communicating information about the unwind
context (i.e. the unwind descriptors and the user register state) between
the unwind library and the personality routine and landing pad. They
include routines to read or set the context record images of registers in
the stack frame corresponding to a given unwind context, and to identify
the location of the current unwind descriptors and unwind frame.

\subsubsection{\code{\_Unwind\_GetGR}}

\code{
\begin{tabular}{l}
    uint64 \_Unwind\_GetGR\\
    \ \ (struct \_Unwind\_Context *context, int index);\\
\end{tabular}
}

This function returns the 64-bit value of the given general register.
The register is identified by its index as given in
figure~\ref{tbl-reg-num-map}.

During the two phases of unwinding, no registers have a guaranteed value.

\subsubsection{\code{\_Unwind\_SetGR}}

\code{
\begin{tabular}{l}
    void \_Unwind\_SetGR\\
    \ \ (struct \_Unwind\_Context *context,\\
    \ \ \ int index,\\
    \ \ \ uint64 new\_value);\\
\end{tabular}
}

This function sets the 64-bit value of the given register, identified by
its index as for \code{\_Unwind\_GetGR}.

The behavior is guaranteed only if the function is called during phase 2
of unwinding, and applied to an unwind context representing a handler frame,
for which the personality routine will return \code{\_URC\_INSTALL\_CONTEXT}.
In that case, only registers \RDI, \RSI, \RDX, \RCX should be used.
These scratch registers are reserved for passing arguments between the
personality routine and the landing pads.

\subsubsection{\code{\_Unwind\_GetIP}}

\code{
\begin{tabular}{l}
    uint64 \_Unwind\_GetIP\\
    \ \ (struct \_Unwind\_Context *context);\\
\end{tabular}
}

This function returns the 64-bit value of the instruction pointer (IP).

During unwinding, the value is guaranteed to be the address of the
instruction immediately following the call site in the function
identified by the unwind context. This value may be outside of the
procedure fragment for a function call that is known to not return
(such as \code{\_Unwind\_Resume}).

Applications which unwind through asynchronous signals and other
non-call locations should use \code{\_Unwind\_GetIPInfo} below, and
the additional flag that function provides.

\subsubsection{\code{\_Unwind\_GetIPInfo}}

\code{
\begin{tabular}{l}
    uint64 \_Unwind\_GetIPInfo\\
    \ \ (struct \_Unwind\_Context *context, int *ip\_before\_insn);\\
\end{tabular}
}

This function returns the same value as \code{\_Unwind\_GetIP}.  In
addition, the argument \code{ip\_before\_insn} must not be not null, and
\code{*ip\_before\_insn} is updated with a flag which indicates whether
the returned pointer is at or after the first not yet fully executed
instruction.

If \code{*ip\_before\_insn} is false, the application calling
\code{\_Unwind\_GetIPInfo} should assume that the instruction pointer
provided points after a call instruction which has not yet returned.
In general, this means that the application should use the preceding
call instruction as the instruction pointer location of the unwind
context.  Typically, this can be approximated by subtracting one from
the returned instruction pointer.

If \code{*ip\_before\_insn} is true, then the instruction pointer does not
refer to an active call site.  Usually, this means that the
instruction pointer refers to the point at which an asynchronous
signal arrived.  In this case, the application should use the
instruction pointer returned from \code{\_Unwind\_GetIPInfo} as the
instruction pointer location of the unwind context, without
adjustment.

\subsubsection{\code{\_Unwind\_SetIP}}
\code{
\begin{tabular}{l}
    void \_Unwind\_SetIP\\
    \ \ (struct \_Unwind\_Context *context,\\
    \ \ \ uint64 new\_value);\\
\end{tabular}
}

This function sets the value of the instruction pointer (IP) for the
routine identified by the unwind context.

The behavior is guaranteed only when this function is called for an
unwind context representing a handler frame, for which the personality
routine will return \code{\_URC\_INSTALL\_CONTEXT}. In this case, control will
be transferred to the given address, which should be the address of a
landing pad.

\subsubsection{\code{\_Unwind\_GetLanguageSpecificData}}

\code{
\begin{tabular}{l}
    uint64 \_Unwind\_GetLanguageSpecificData\\
            (struct \_Unwind\_Context *context);\\
\end{tabular}
}

\begin{sloppypar}
This routine returns the address of the language-specific data area for
the current stack frame.

This routine is not strictly required: it could be accessed through
\code{\_Unwind\_GetIP} using the documented format of the DWARF Call Frame
Information Tables, but since this work has been done for finding the
personality routine in the first place, it makes sense to cache the
result in the context.
We could also pass it as an argument to the personality routine.
\end{sloppypar}

\subsubsection{\code{\_Unwind\_GetRegionStart}}

\code{
\begin{tabular}{l}
    uint64 \_Unwind\_GetRegionStart\\
    \ \ (struct \_Unwind\_Context *context);\\
\end{tabular}
}

This routine returns the address of the beginning of the procedure or
code fragment described by the current unwind descriptor block.

This information is required to access any data stored relative to the
beginning of the procedure fragment. For instance, a call site table
might be stored relative to the beginning of the procedure fragment
that contains the calls. During unwinding, the function returns the
start of the procedure fragment containing the call site in the current
stack frame.

\subsubsection{\code{\_Unwind\_GetCFA}}

\code{
\begin{tabular}{l}
    uint64 \_Unwind\_GetCFA\\
    \ \ (struct \_Unwind\_Context *context);\\
\end{tabular}
}

This function returns the 64-bit Canonical Frame Address which
is defined as the value of \RSP at the call site in the
previous frame.  This value is guaranteed to be correct any
time the context has been passed to a personality routine or a
stop function.

% XXX: Disable for now
%\paragraph{Example: back-trace\\}
%
%An example of using some of the introduced functions is the
%\codeindex{backtrace()} function that shows all callers of a function.  It
%can be implemented as shown in figure~\ref{fig-backtrace}.
%
%\begin{figure}[H]
%\Hrule
%\caption{Frame Unwinding Example}
%\label{fig-backtrace}
%{\small
%\begin{verbatim}
%_Unwind_Reason_Code
%walk_stack (int ver, _Unwind_Action actions,
%            _Unwind_Exception_Class exc_class,
%            struct _Unwind_Exception *exc,
%            struct _Unwind_Context *ctx, void *data)
%{
%  printf ("Instruction: %lx in region %lx\n",
%          _Unwind_GetIP (ctx),
%          _Unwind_GetRegionStart(ctx));
%
%  return _URC_NO_REASON;
%}
%
%void
%no_cleanup (_Unwind_Reason_Code code,
%            struct _Unwind_Exception *exc)
%{/* Nothing to do.  Just to make
%    _Unwind_ForcedUnwind happy.  */
%}
%
%void
%backtrace_stack (void)
%{
%  struct _Unwind_Exception exc;
%
%  exc.exception_class = 0;
%  exc.exception_cleanup = no_cleanup;
%  _Unwind_ForcedUnwind (&exc, walk_stack, NULL);
%}
%\end{verbatim}
%}
%\Hrule
%\end{figure}
%
\subsection{Personality Routine}

\code{
\begin{tabular}{l}
    \_Unwind\_Reason\_Code (*\_\_personality\_routine)\\
    \ \ (int version,\\
    \ \ \ \_Unwind\_Action actions,\\
    \ \ \ uint64 exceptionClass,\\
    \ \ \ struct \_Unwind\_Exception *exceptionObject,\\
    \ \ \ struct \_Unwind\_Context *context);\\
\end{tabular}
}

The personality routine is the function in the C++ (or other language)
runtime library which serves as an interface between the system
unwind library and language-specific exception handling semantics.
It is specific to the code fragment described by an unwind info block,
and it is always referenced via the pointer in the unwind info block,
and hence it has no psABI-specified name.

\subsubsection{Parameters}

The personality routine parameters are as follows:

\begin{description}
\item[\code{version}] Version number of the unwinding runtime,
   used to detect a mis-match between the unwinder conventions and the
   personality routine, or to provide backward compatibility. For the
   conventions described in this document, version will be 1.
\item[\code{actions}] Indicates what processing the personality routine
   is expected to perform, as a bit mask. The possible actions are
   described below.
\item[\code{exceptionClass}] An 8-byte identifier specifying the type of the
   thrown exception. By convention, the high 4 bytes indicate the vendor
   (for instance AMD$\backslash$0), and the low 4 bytes indicate
   the language.  For the C++ ABI described in this document, the low
   four bytes are C++$\backslash$0.  This is not a null-terminated string.
   Some implementations may use no null bytes.
\item[\code{exceptionObject}] The pointer to a memory location recording the
   necessary information for processing the exception according to the
   semantics of a given language (see the Exception Header section above).
\item[\code{context}] Unwinder state information for use by the personality routine.
   This is an opaque handle used by the personality routine in particular
   to access the frame's registers (see the Unwind Context section above).
\item[return value] The return value from the personality routine indicates
   how further unwind should happen, as well as possible error conditions.
   See the following section.
\end{description}

\subsubsection{Personality Routine Actions}

The actions argument to the personality routine is a bitwise OR of one or
more of the following constants: \\
\code{
    typedef int \_Unwind\_Action;\\
    const \_Unwind\_Action \_UA\_SEARCH\_PHASE = 1;\\
    const \_Unwind\_Action \_UA\_CLEANUP\_PHASE = 2;\\
    const \_Unwind\_Action \_UA\_HANDLER\_FRAME = 4;\\
    const \_Unwind\_Action \_UA\_FORCE\_UNWIND = 8;\\
}

\begin{description}
\item[\code{\_UA\_SEARCH\_PHASE}] Indicates that the personality routine should
   check if the current frame contains a handler, and if so return
   \code{\_URC\_HANDLER\_FOUND}, or otherwise return \code{\_URC\_CONTINUE\_UNWIND}.
   \code{\_UA\_SEARCH\_PHASE} cannot be set at the same time as \code{\_UA\_CLEANUP\_PHASE}.

\item[\code{\_UA\_CLEANUP\_PHASE}]
\begin{sloppypar}
   Indicates that the personality routine should
   perform cleanup for the current frame. The personality routine can perform
   this cleanup itself, by calling nested procedures, and return
   \code{\_URC\_CONTINUE\_UNWIND}. Alternatively, it can setup the registers
   (including the IP) for transferring control to a "landing pad", and
   return \code{\_URC\_INSTALL\_CONTEXT}.
\end{sloppypar}

\item[\code{\_UA\_HANDLER\_FRAME}]
   During phase 2, indicates to the personality routine that the current
   frame is the one which was flagged as the handler frame during phase 1.
   The personality routine is not allowed to change its mind between phase 1
   and phase 2, i.e. it must handle the exception in this frame in phase 2.

\item[\code{\_UA\_FORCE\_UNWIND}] During phase 2, indicates that no language is
   allowed to "catch" the exception. This flag is set while unwinding the
   stack for \code{longjmp} or during thread cancellation. User-defined code in a
   catch clause may still be executed, but the catch clause must resume
   unwinding with a call to \code{\_Unwind\_Resume} when finished.
\end{description}

\subsubsection{Transferring Control to a Landing Pad}

If the personality routine determines that it should transfer control to a
landing pad (in phase 2), it may set up registers (including IP) with
suitable values for entering the landing pad (e.g. with landing pad
parameters), by calling the context management routines above. It then
returns \code{\_URC\_INSTALL\_CONTEXT}.

Prior to executing code in the landing pad, the unwind library restores
registers not altered by the personality routine, using the context
record, to their state in that frame before the call that threw the exception,
as follows. All registers specified as callee-saved by the base ABI are
restored, as well as scratch registers \RDI, \RSI, \RDX, \RCX (see below).
Except for those exceptions, scratch (or caller-saved) registers are not
preserved, and their contents are undefined on transfer.

The landing pad can either resume normal execution (as, for instance, at
the end of a C++ catch), or resume unwinding by calling \code{\_Unwind\_Resume} and
passing it the \code{exceptionObject} argument received by the personality routine.
\code{\_Unwind\_Resume} will never return.

\code{\_Unwind\_Resume} should be called if and only if the personality routine
did not return \code{\_Unwind\_HANDLER\_FOUND} during phase 1.  As a result,
the unwinder can allocate resources (for instance memory) and keep track
of them in the exception object reserved words. It should then free these
resources before transferring control to the last (handler) landing pad.
It does not need to free the resources before entering non-handler
landing-pads, since \code{\_Unwind\_Resume} will ultimately be called.

\begin{sloppypar}
The landing pad may receive arguments from the runtime, typically passed
in registers set using \code{\_Unwind\_SetGR} by the personality routine.
For a landing pad that can call to \code{\_Unwind\_Resume}, one argument must
be the \code{exceptionObject} pointer, which must be preserved to be passed to
\code{\_Unwind\_Resume}.
\end{sloppypar}

The landing pad may receive other arguments, for instance a switch value
indicating the type of the exception. Four scratch registers are reserved
for this use (\RDI, \RSI, \RDX, \RCX).

\subsubsection{Rules for Correct Inter-Language Operation}

The following rules must be observed for correct operation between
languages and/or run times from different vendors:

An exception which has an unknown class must not be altered by the
personality routine. The semantics of foreign exception processing
depend on the language of the stack frame being unwound. This covers
in particular how exceptions from a foreign language are mapped to
the native language in that frame.

If a runtime resumes normal execution, and the caught exception was
created by another runtime, it should call \code{\_Unwind\_DeleteException}.
This is true even if it understands the exception object format
(such as would be the case between different C++ run times).

A runtime is not allowed to catch an exception if the
\code{\_UA\_FORCE\_UNWIND} flag was passed to the personality routine.

\paragraph{Example: Foreign Exceptions in C++.}
\begin{sloppypar}
In C++, foreign exceptions can be
caught by a \code{catch(\dots)} statement. They can also be caught as if they
were of a \code{\_\_foreign\_exception} class, defined in \code{<exception>}. The
\code{\_\_foreign\_exception} may have subclasses, such as
\code{\_\_java\_exception} and \code{\_\_ada\_exception}, if the runtime is capable
of identifying some of the foreign languages.
\end{sloppypar}

The behavior is undefined in the following cases:
\begin{itemize}
\item A \code{\_\_foreign\_exception} catch argument is accessed in any way
     (including taking its address).

\item A \code{\_\_foreign\_exception} is active at the same time as another
     exception (either there is a nested exception while catching the
     foreign exception, or the foreign exception was itself nested).

\item \code{uncaught\_exception()}, \code{set\_terminate()},
     \code{set\_unexpected()}, \code{terminate()}, or
     \code{unexpected()} is called at a time a foreign exception
     exists (for example, calling \code{set\_terminate()} during
     unwinding of a foreign exception).
\end{itemize}

All these cases might involve accessing C++ specific content of the
thrown exception, for instance to chain active exceptions.

Otherwise, a catch block catching a foreign exception is allowed:
\begin{itemize}
\item to resume normal execution, thereby stopping propagation of
      the foreign exception and deleting it, or
\item to re-throw the foreign exception. In that case, the original
      exception object must be unaltered by the C++ runtime.
\end{itemize}

A catch-all block may be executed during forced unwinding.  For
instance, a longjmp may execute code in a \code{catch(\dots)} during
stack unwinding. However, if this happens, unwinding will proceed at
the end of the catch-all block, whether or not there is an explicit
re-throw.

Setting the low 4 bytes of exception class to C++$\backslash$0 is reserved
for use by C++ run-times compatible with the common C++ ABI.

\section{Unwinding Through Assembler Code}

For successful unwinding on \xARCH every function must provide a valid
debug information in the \textindex{DWARF Debugging Information
  Format}. In high level languages (e.g. C/C++, Fortran, Ada, ...)
this information is generated by the compiler itself. However for
hand-written assembly routines the debug info must be provided by the
author of the code. To ease this task some new assembler directives
are added:

\begin{description}
\item[\codeindex{.cfi\_startproc}] is used at the beginning of each
  function that should have an entry in \codeindex{.eh\_frame}. It
  initializes some internal data structures and emits architecture
  dependent initial CFI instructions.  Each \code{.cfi\_startproc}
  directive has to be closed by \code{.cfi\_endproc}.
  
\item[\codeindex{.cfi\_endproc}] is used at the end of a function
  where it closes its unwind entry previously opened by
  \code{.cfi\_startproc} and emits it to \code{.eh\_frame}.

\item[\codeindex{.cfi\_def\_cfa}\code{REGISTER, OFFSET}] defines a
  rule for computing CFA as: take address from REGISTER and add OFFSET
  to it.
  
\item[\codeindex{.cfi\_def\_cfa\_register}\code{REGISTER}] modifies a
  rule for computing CFA. From now on REGISTER will be used instead of
  the old one. The offset remains the same.
  
\item[\codeindex{.cfi\_def\_cfa\_offset}\code{OFFSET}] modifies a rule for
  computing CFA. The register remains the same, but OFFSET is new.
  Note that this is the absolute offset that will be added to a defined
  register to compute the CFA address.
  
\item[\codeindex{.cfi\_adjust\_cfa\_offset}\code{OFFSET}] is similar to
  \code{.cfi\_def\_cfa\_offset} but OFFSET is a relative value that is
  added or subtracted from the previous offset.
  
\item[\codeindex{.cfi\_offset}\code{REGISTER, OFFSET}] saves the previous
  value of REGISTER at offset OFFSET from CFA.
  
\item[\codeindex{.cfi\_rel\_offset}\code{REGISTER, OFFSET}] saves the
  previous value of REGISTER at offset OFFSET from the current CFA
  register.  This is transformed to \code{.cfi\_offset} using the
  known displacement of the CFA register from the CFA.  This is often
  easier to use, because the number will match the code it is
  annotating.
  
\item[\codeindex{.cfi\_escape}\code{EXPRESSION[, ...]}]  allows the user to
  add arbitrary bytes to the unwind info.  One might use this to add
  OS-specific CFI opcodes, or generic CFI opcodes that the assembler
  does not support.
\end{description}

\begin{figure}[H]
\Hrule
\caption{Examples for Unwinding in Assembler}
\label{fig_asm_unwinding}
\begin{center}
\begin{small}
\begin{verbatim}
# - function with local variable allocated on the stack
        .type   func_locvars,@function
func_locvars:
        .cfi_startproc
        # allocate space for local vars
        sub     $0x1234, %rsp
        .cfi_adjust_cfa_offset  0x1234
        # body
        ...
        # release space of local vars and return
        add     $0x1234, %rsp
        .cfi_adjust_cfa_offset  -0x1234
        ret
        .cfi_endproc

# - function that moves frame pointer to another register
#   and then allocates space for local variables
        .type   func_otherreg,@function
func_otherreg:
        .cfi_startproc
        # save frame pointer to r12
        movq    %rsp, %r12
        .cfi_def_cfa_register   r12
        # allocate space for local vars 
        # (no .cfi_{def,adjust}_cfa_offset needed here, 
        # because CFA is computed from r12!)
        sub     $100,%rsp
        # body
        ...
        # restore frame pointer from r12
        movq    %r12, %rsp
        .cfi_def_cfa_register   rsp
        ret
        .cfi_endproc
\end{verbatim}
\end{small}
\end{center}
\Hrule
\end{figure}

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "abi"
%%% End: