[Doc] Guideline on adding exception handling support for a target

[chenwj]

Summary

This is the first attempt to write down a guideline on adding exception handling support for a target. The content basically bases on the discussion on [1]. If you guys know who is exception handling expert, please add him as the reviewer. Thanks.

[1] http://lists.llvm.org/pipermail/llvm-dev/2018-January/120405.html

[theraven]

Thank you very much for making a start on this!

docs/ExceptionHandling.rst

853

Most of this is generic code. The important thing for the back end is to make sure that every register has a unique DWARF number.

In your TargetFrameLowering's emitPrologue method, you must add the .cfi_def_cfa_offset directive for the frame and then the .cfi_def_cfa_register or similar to tell the unwinder the base address for all subsequent offsets.

860

Perhaps note that the first of these contains a pointer and the second an integer. On most platforms, they will be GPRs, but on any architecture with distinct address and integer registers the first will likely be an address.

865

Perhaps document what this does? I believe that it's an undocumented GCC extension that is used only in the GNU unwinder (LLVM's libUnwind doesn't use it). According to comments in the MIPS back end, it is of the form __builtin_eh_return (offset, handler) and adjusts the stack by offset and then jumps to the handler.

870

It would be good to enumerate the things that are needed to get this working. This diff adds 64-bit MIPS support (soft-float only):

https://github.com/CTSRD-CHERI/libunwind/commit/7b3c8ca32786b7b63975f3c5f93f41d69578416b

It contains a bug where a couple of registers that should have been saved weren't, but it provides an example of all of the things that you need to add to support a new architecture.

The only difficult thing is correctly setting _LIBUNWIND_CONTEXT_SIZE and _LIBUNWIND_CURSOR_SIZE - you get a compile error that tells you if you got them wrong, but it doesn't tell you what the correct size should be. I did this by temporarily replacing the static_assert with a template that invoked static_assert and gave me the arguments in the failure backtrace.

[chenwj]

@theraven For `libunwind` part, I am not sure if it's okay to include your link there. I just skim through the patch and list the key points I thought.

[chenwj]

@theraven, ping?

[theraven]

I'm inclined to recommend that you commit this. It's not perfect, but it's a *lot* better than what was there before, and hopefully having something there will encourage other people to improve it.

[chenwj]

@theraven Could you commit this for me? I will be happy to update the context if I have more experience on this.

[theraven]

I appear to have lost my credentials for LLVM svn. I've asked Chris to reset them, but someone else should feel free to commit this before then if they want to.

docs/ExceptionHandling.rst

 unwind as ``nounwind``, it is legal to nest a ``call`` or an "``unwind to
 caller``\ " ``catchswitch`` within a funclet pad that has an unwind
 destination other than caller; it is undefined behavior for such a ``call``
 or ``catchswitch`` to unwind.
 
 Finally, the funclet pads' unwind destinations cannot form a cycle.  This
 ensures that EH lowering can construct "try regions" with a tree-like
 structure, which funclet-based personalities may require.
+
+Exception Handling support on the target
+=================================================
+
+In order to support exception handling on particular target, there are a few
+items need to be implemented.
+
+* CFI directives
+
+  First, you have to assign each target register with a unique DWARF number.
+  Then in ``TargetFrameLowering``'s ``emitPrologue``, you have to emit `CFI
+  directives <https://sourceware.org/binutils/docs/as/CFI-directives.html>`_
+  to specify how to calculate the CFA (Canonical Frame Address) and how register
+  is restored from the address pointed by the CFA with an offset. The assembler
+  is instructed by CFI directives to build ``.eh_frame`` section, which is used
+  by th unwinder to unwind stack during exception handling.
+
+* ``getExceptionPointerRegister`` and ``getExceptionSelectorRegister``
+
+  ``TargetLowering`` must implement both functions. The *personality function*
+  passes the *exception structure* (a pointer) and *selector value* (an integer)
+  to the landing pad through the registers specified by ``getExceptionPointerRegister``
+  and ``getExceptionSelectorRegister`` respectively. On most platforms, they
+  will be GPRs and will be the same as the ones specified in the calling convention.
+
+* ``EH_RETURN``
+
+  The ISD node represents the undocumented GCC extension ``__builtin_eh_return (offset, handler)``,
+  which adjusts the stack by offset and then jumps to the handler. ``__builtin_eh_return``
+  is used in GCC unwinder (`libgcc <https://gcc.gnu.org/onlinedocs/gccint/Libgcc.html>`_),
+  but not in LLVM unwinder (`libunwind <https://clang.llvm.org/docs/Toolchain.html#unwind-library>`_).
+  If you are on the top of ``libgcc`` and have particular requirement on your target,
+  you have to handle ``EH_RETURN`` in ``TargetLowering``.
+
+If you don't leverage the existing runtime (``libstdc++`` and ``libgcc``),
+you have to take a look on `libc++ <https://libcxx.llvm.org/>`_ and
+`libunwind <https://clang.llvm.org/docs/Toolchain.html#unwind-library>`_
+to see what have to be done there. For ``libunwind``, you have to do the following
+
+* ``__libunwind_config.h``
+
+  Define macros for your target.
+
+* ``include/libunwind.h``
+
+  Define enum for the target registers.
+
+* ``src/Registers.hpp``
+
+  Define ``Registers`` class for your target, implement setter and getter functions.
+
+* ``src/UnwindCursor.hpp``
+
+  Define ``dwarfEncoding`` and ``stepWithCompactEncoding`` for your ``Registers``
+  class.
+
+* ``src/UnwindRegistersRestore.S``
+
+  Write an assembly function to restore all your target registers from the memory.
+
+* ``src/UnwindRegistersSave.S``
+
+  Write an assembly function to save all your target registers on the memory.