Re: [lsb-spec] Re: Standardizing _Unwind_* error handling interfa ces found in libgcc_s.so

[Jim Wilson <wilson at redhat dot com>]

Richard Henderson knows more about this stuff than I do, but I think I
can give an accurate answer.

The bulk of the functions come from the IA-64 Unwind API.  This API is included
in both the IA-64 ABI and the machine-independent C++ ABI.  Gcc uses this
API for all targets for stack unwinding for C++/Java exception handling.
We have 3 versions of these functions, one for the IA-64 Unwind ABI, one for
our own DWARF2 CFI-variant unwind ABI, and one for an option of last resort
setjmp/longjmp unwind ABI.  These functions are:
        _Unwind_DeleteException
        _Unwind_ForcedUnwind
        _Unwind_GetGR
        _Unwind_GetIP
        _Unwind_GetLanguageSpecificData
        _Unwind_GetRegionStart
        _Unwind_RaiseException
        _Unwind_Resume
        _Unwind_SetGR
        _Unwind_SetIP
The ForcedUnwind function was apparently accidentally left out of the original
list.  Further info on these functions can be found by consulting the IA-64
Unwind API, or the IA-64 ABI, or the C++ ABI.

There is one place where the IA-64 Unwind API does some hand waving, and says
that the OS will provide a function for accessing the unwind info, but does
not specify the name of the function or how it works.  We have abstracted this
by adding our own function to the list.  This function is
        _Unwind_Find_FDE
We have an OS independent version of this function for the DWARF2 CFI-variant
unwind ABI.  However, for the IA-64 Unwind ABI, we need OS dependent versions
of this function.  We have a glibc specific version for linux.  We will need
to add versions for other operating systems, like ia64-hpux for instance.
We don't need a version of this for the setjmp/longjmp unwind ABI.

There is a second related place where the IA-64 Unwind API does not specify
how to perform an operation, though it doesn't actually document this.  In
the IA-64 Unwind ABI, unwind info uses section relative relocations.  This
means we need some OS specific mechanism for finding section addresses in
the unwind library at run time.  We have abstracted this into two additional
functions:
        _Unwind_GetDataRelBase
        _Unwind_GetTextRelBase
The original list says these are IA-64 specific.  This isn't strictly correct,
though this gets a bit complicated.  These functions are specific to the IA-64
Unwind ABI, because at present is it the only Unwind ABI that uses section
relative relocations.  However, it is possible that other Unwind ABIs in the
future will need to use them.  Also, since the IA-64 target is the only target
using the IA-64 Unwind ABI at present, they are in that sense specific to the
IA-64 target.  However, it is possible that other targets in the future may
use the IA-64 Unwind ABI.  Since gcc is abstracting this stuff, we actually
define these functions for all 3 Unwind ABIs that we support, so that they
are available for all targets.  Hence the LSB should not document these as
IA-64 specific functions.  We have a glibc specific version of these functions
for ia64-linux.  For other targets you get default versions that may or may
not be working, since I don't think they are used at present.

There is a futher complication here in that since the IA-64 Unwind API is
part of the IA-64 ABI, adding functions to the IA-64 Unwind API violates
the IA-64 ABI.  Therefore, for the IA-64 target only, we have taken steps to
avoid use of functions that are not in the IA-64 Unwind API.  Our glibc
specific implementation for ia64-linux defines hooks so that these two
functions will never be defined or used.  We instead use info set up by the
_Unwind_Find_FDE function.  For other IA-64 targets, we provide default
(probably non-working) static inline versions of these functions.  I'm not
sure whether this is really useful, considering that we still need the
_Unwind_Find_FDE function, and if we need one non-standard function, we may
as well have 3, but perhaps I missed something here.

To summarize, there are 13 functions, not 12, and none of them are IA-64 ABI
specific.  Some are not used for some targets, but they are all provided for
all targets.  There is one unwind API.  There are three unwind ABIs.

I've used Unwind API to refer to the list of functions that C++/Java code calls
to perform stack unwind operations.  I've used Unwind ABI to refer to the
low level representation of the unwind info used by the Unwind API library.

Jim