[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
+
+  TargetFrameLowering must emit CFI directives in the prologue to build
+  ``.eh_frame`` section. Unwinder uses the information stored in ``.eh_frame``
+  to unwind stack.
+
+* ``getExceptionPointerRegister`` and ``getExceptionSelectorRegister``
+
+  TargetLowering must implement both functions. The *personality function*
+  passes the *exception structure* and *selector value* to the landing pad
+  through the registers specified by ``getExceptionPointerRegister`` and
+  ``getExceptionSelectorRegister`` respectively.
+
+* ``EH_RETURN``
+
+  The ISD node represents ``__builtin_eh_return``. Depends on your target,
+  you might 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.