RFC: The unwind specification draft for GNU/Linux/ia64

["H. J. Lu" <hjl at lucon dot org>]

The current unwind specification for GNU/Linux/ia64 does't specify how
to provide the binary compatibilty when the 3rd part unwind library
is used. As the result, gcc configured with libunwind isn't compatible
with gcc without libunwind:

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=14925

This proposal tries to address this issue. I have talked with David,
Mark and Intel compiler people. We think it is a feasible solution.
If there are no major objections, I will start work on a patch to
extract the unwind library from libgcc_so and put it in libunwind.so.7.
The new libgcc_so will be backward binary compatible with the previous
libgcc_so.


H.J.
----
This is the unwind specification draft for GNU/Linux/ia64 which extends the exception ABI:

http://www.codesourcery.com/cxx-abi/abi-eh.html

Its goals are

1. Allow any ABI conforming shared unwind library to be used with output from any ABI compliant GNU/Linux compiler.
2. Support linking relocatable object files generated by different ABI compliant GNU/Linux compilers.

The GNU/Linux/ia64 extension of the "Level I. Base ABI" section in the exception ABI:

1. An implementation of a shared unwind library shall place the unwind library in a DSO named libunwind.so.7 or in auxiliary DSOs automatically loaded by it.
2. A new unwind action:

	const _Unwind_Action _UA_END_OF_STACK = 16;

In order to allow _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 the _UA_END_OF_STACK bit in action on, and the stop function must catch this condition (i.e. by noticing that the _UA_END_OF_STACK bit in action is on). It may return this reason code if it cannot handle end-of-stack.

3. Additional functions:

a. Use unwind data to perform a stack backtrace.  The trace callback is called for every stack frame in the call chain, but no cleanup actions are performed.

    typedef _Unwind_Reason_Code (*_Unwind_Trace_Fn)
    (struct _Unwind_Context *, void *);

    extern _Unwind_Reason_Code _Unwind_Backtrace (_Unwind_Trace_Fn, void *);
b. Retrieve the Backing Store Pointer of the given context.
    extern _Unwind_Word _Unwind_GetBSP (struct _Unwind_Context *);
c. Retrieve the CFA of the given context.
    extern _Unwind_Word _Unwind_GetCFA (struct _Unwind_Context *);
d. extern _Unwind_Ptr _Unwind_GetDataRelBase (struct _Unwind_Context *);
e. extern _Unwind_Ptr _Unwind_GetTextRelBase (struct _Unwind_Context *);
f. Resume propagation of an FORCE_UNWIND exception, or to rethrow a normal exception that was handled.  */
    extern _Unwind_Reason_Code _Unwind_Resume_or_Rethrow (struct _Unwind_Exception *);
g. Given an address, return the entry point of the function that contains it.
    extern void * _Unwind_FindEnclosingFunction (void *pc);
	
The GNU/Linux/ia64 extension of the "Level III. Suggested Implementation" section in the exception ABI:

1. An implementation of GNU/Linux compiler shall provide the personality routine, __gnu_linux_[language]_personality_v0.
h. For C, it will be __gnu_linux_c_personality_v0.
i. For C++, it will be __gnu_linux_cxx_personality_v0.
j. Other languages?

2. The GNU/Linux compiler can generate the personality data describing cleanup handlers, which is encoded in DWARF-2.
3. The GNU/Linux personality routine shall handle cleanup handlers.

Other GNU/Linux platforms shall adopt the above specification if the platform ABI doesn't specify an alternate unwind mechanism.

Backward compatibility for the existing libgcc-based unwinder:

If there is an existing libgcc-based unwinder in gcc and an unwind library supports gcc, a set of compatibility symbols should be defined.

1. __libunwind_Unwind_Backtrace: Alias of _Unwind_Backtrace
2. __libunwind_Unwind_DeleteException: Alias of _Unwind_DeleteException
3. __libunwind_Unwind_FindEnclosingFunction: Alias of _Unwind_FindEnclosingFunction
4. __libunwind_Unwind_ForcedUnwind: Alias of _Unwind_ForcedUnwind
5. __libunwind_Unwind_GetBSP: Alias of _Unwind_GetBSP
6. __libunwind_Unwind_GetCFA: Alias of _Unwind_GetCFA
7. __libunwind_Unwind_GetGR: Alias of _Unwind_GetGR
8. __libunwind_Unwind_GetIP: Alias of _Unwind_GetIP
9. __libunwind_Unwind_GetLanguageSpecificData: Alias of _Unwind_GetLanguageSpecificData
10. __libunwind_Unwind_GetRegionStart: Alias of _Unwind_GetRegionStart
11. __libunwind_Unwind_RaiseException: Alias of _Unwind_RaiseException
12. __libunwind_Unwind_Resume: Alias of _Unwind_Resume
13. __libunwind_Unwind_Resume_or_Rethrow: Alias of _Unwind_Resume_or_Rethrow
14. __libunwind_Unwind_SetGR: Alias of _Unwind_SetGR
15. __libunwind_Unwind_SetIP: Alias of _Unwind_SetIP

Those symbols can be used by the new libgcc to provide the backward binary compatibility.