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

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

[Wichmann, Mats D]

=
> It's also not clear if they're CPU-specific.  I know that 
> some of these 
> are actually in the psABI on x86-64.

Just two were listed as ia64 CPU-specific
(interestingly, those two don't appear in the ia64 psABI,
I'm still curious where they come from).

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

[Jim Wilson]

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

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

[Richard Henderson]

On Thu, Oct 10, 2002 at 05:16:09PM -0400, Jim Wilson wrote:
> Gcc uses this
> API for all targets for stack unwinding for C++/Java exception handling.

In theory it would be used for Ada exception handling as well,
but no one's contributed code for that yet.

> The ForcedUnwind function was apparently accidentally left out of the
> original list.

The _Unwind_ForcedUnwind function is present, but it hasn't really been
tested, and I doubt it works properly.

>         _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.

I would say that this function is still private.  It is exported
from libgcc_s.so in order to solve a nasty backward compatibility
problem with glibc.

The function that accomplishes a similar task for IA-64 is 
_Unwind_FindTableEntry, and that function is _not_ exported.

> 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.

This is incorrect.  These functions are even more abstract than the
section-relative descriptions used by the IA-64 Unwind API.

Our dwarf2 cfi extension has some metadata that describes how a 
pointer is encoded within the format itself.  Encodings are desirable
so that the cfi data can be position-independent, and thus not require
runtime relocations in shared libraries.  Which encodings can be used
for a particular target depends on the relocation types provided.

Two of these encodings are "text-relative" and "data-relative", with
no specific meaning associated with either.  These two functions 
return the base to which these encodings are relative.

Incidentally, x86 uses "data-relative" encodings, where DataRelBase
is _GLOBAL_OFFSET_TABLE_.

These functions are universally present in the API provided by
gcc's unwind.h (which probably ought to get installed, but isn't).
In the case of IA-64, these functions are inlines which fall back
on the generic IA-64 EH ABI entry points so that we are ABI compatible
with other IA-64 implementations.




r~

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

[Jim Wilson]

I thought of another thing I should clarify.

If you are documenting functions that might appear in a gcc compiled
executable, then you want to mention all 13 functions.

If you are documenting functions that are meant for application use, then
you should only mention the first 10 functions I listed.  These are the 10
functions that are part of the IA-64 Unwind API.

The other 3 functions that gcc added on top of the IA-64 Unwind API
        _Unwind_Find_FDE
        _Unwind_GetDataRelBase
        _Unwind_GetTextRelBase
solve Unwind ABI library implementation details.  They are not meant for
application use.  They are meant for use by other Unwind ABI libraries.  Since
gcc only really supports its own unwind ABI libraries at present, we don't
always bother to provide working versions of these functions.  Hence they are
not safe for general application use.  They are only safe if you know what you
are doing.

Jim

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

[H. Peter Anvin]

Jim Wilson wrote:
> I thought of another thing I should clarify.
> 
> If you are documenting functions that might appear in a gcc compiled
> executable, then you want to mention all 13 functions.
> 
> If you are documenting functions that are meant for application use, then
> you should only mention the first 10 functions I listed.  These are the 10
> functions that are part of the IA-64 Unwind API.
> 
> The other 3 functions that gcc added on top of the IA-64 Unwind API
>         _Unwind_Find_FDE
>         _Unwind_GetDataRelBase
>         _Unwind_GetTextRelBase
> solve Unwind ABI library implementation details.  They are not meant for
> application use.  They are meant for use by other Unwind ABI libraries.  Since
> gcc only really supports its own unwind ABI libraries at present, we don't
> always bother to provide working versions of these functions.  Hence they are
> not safe for general application use.  They are only safe if you know what you
> are doing.
> 

LSB is about documenting the ABI, so they should be included unless an
application is required to link statically against this library.

	-hpa