llvm.org GIT mirror llvm / e8a15e2
[Doc] Guideline on adding exception handling support for a target 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 Reviewers: t.p.northover, theraven, nemanjai Reviewed By: theraven Subscribers: sdardis, llvm-commits Differential Revision: https://reviews.llvm.org/D42178 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@323311 91177308-0d34-0410-b5e6-96231b3b80d8 David Chisnall 1 year, 8 months ago
1 changed file(s) with 63 addition(s) and 0 deletion(s). Raw diff Collapse all Expand all
838838 Finally, the funclet pads' unwind destinations cannot form a cycle. This
839839 ensures that EH lowering can construct "try regions" with a tree-like
840840 structure, which funclet-based personalities may require.
841
842 Exception Handling support on the target
843 =================================================
844
845 In order to support exception handling on particular target, there are a few
846 items need to be implemented.
847
848 * CFI directives
849
850 First, you have to assign each target register with a unique DWARF number.
851 Then in ``TargetFrameLowering``'s ``emitPrologue``, you have to emit `CFI
852 directives `_
853 to specify how to calculate the CFA (Canonical Frame Address) and how register
854 is restored from the address pointed by the CFA with an offset. The assembler
855 is instructed by CFI directives to build ``.eh_frame`` section, which is used
856 by th unwinder to unwind stack during exception handling.
857
858 * ``getExceptionPointerRegister`` and ``getExceptionSelectorRegister``
859
860 ``TargetLowering`` must implement both functions. The *personality function*
861 passes the *exception structure* (a pointer) and *selector value* (an integer)
862 to the landing pad through the registers specified by ``getExceptionPointerRegister``
863 and ``getExceptionSelectorRegister`` respectively. On most platforms, they
864 will be GPRs and will be the same as the ones specified in the calling convention.
865
866 * ``EH_RETURN``
867
868 The ISD node represents the undocumented GCC extension ``__builtin_eh_return (offset, handler)``,
869 which adjusts the stack by offset and then jumps to the handler. ``__builtin_eh_return``
870 is used in GCC unwinder (`libgcc `_),
871 but not in LLVM unwinder (`libunwind `_).
872 If you are on the top of ``libgcc`` and have particular requirement on your target,
873 you have to handle ``EH_RETURN`` in ``TargetLowering``.
874
875 If you don't leverage the existing runtime (``libstdc++`` and ``libgcc``),
876 you have to take a look on `libc++ `_ and
877 `libunwind `_
878 to see what have to be done there. For ``libunwind``, you have to do the following
879
880 * ``__libunwind_config.h``
881
882 Define macros for your target.
883
884 * ``include/libunwind.h``
885
886 Define enum for the target registers.
887
888 * ``src/Registers.hpp``
889
890 Define ``Registers`` class for your target, implement setter and getter functions.
891
892 * ``src/UnwindCursor.hpp``
893
894 Define ``dwarfEncoding`` and ``stepWithCompactEncoding`` for your ``Registers``
895 class.
896
897 * ``src/UnwindRegistersRestore.S``
898
899 Write an assembly function to restore all your target registers from the memory.
900
901 * ``src/UnwindRegistersSave.S``
902
903 Write an assembly function to save all your target registers on the memory.