[llvm-bugs] [Bug 38412] New: The Windows exception handling documentation omits important details.

[via llvm-bugs]

https://bugs.llvm.org/show_bug.cgi?id=38412

            Bug ID: 38412
           Summary: The Windows exception handling documentation omits
                    important details.
           Product: Documentation
           Version: trunk
          Hardware: All
                OS: All
            Status: NEW
          Severity: enhancement
          Priority: P
         Component: General docs
          Assignee: unassignedbugs at nondot.org
          Reporter: b.helyer at gmail.com
                CC: llvm-bugs at lists.llvm.org

I work on the Volta (http://www.volt-lang.org/) compiler, a work-in-progress
compiler for a new language that is using LLVM. This week I've been working on
implementing exception handling on 64 bit Windows, a feature that LLVM has
relatively recently added.

If you don't know what you're doing (like me) the documentation that exists
omits a few key pieces of information that took me a few days of going down the
wrong paths until I had just gave up and read the LLVM source code to figure
out what was happening.

https://llvm.org/docs/ExceptionHandling.html#new-exception-handling-instructions

"While they can be used to represent Itanium EH, the landingpad model is
strictly better for optimization purposes."

This sentence is very badly missing a "theoretically" or "in theory" to
emphasise that you can't actually use catchpad and friends to implement Itanium
EH (they only work for a subset of personality functions, more on that later).
While this didn't personally cause me any issues (we already have a landingpad
etc implementation for macOS and Linux) I did initially think that this
sentence meant that you could implement Itanium EH and Windows EH using
catchpad, which is not true, as far as I can tell.

Some background. In EHPersonalities.cpp, llvm::classifyEHPersonality classifies
the personality functions, and it does this by switching on the name and
returning an EHPersonality value appropriate for that personality function. In
EHPersonalities.h there's a function, isScopedEHPersonality. Quoth the
comments:

/// Returns true if this personality uses scope-style EH IR instructions:
/// catchswitch, catchpad/ret, and cleanuppad/ret.

This returns true for MSVC_CXX, MSVC_X86SEH, MSVC_Win64SEH, CoreCLR, and
Wasm_CXX values. That is to say, if the personality function is named
_except_handler3, _except_handler4, __C_specific_handler, __CxxFrameHandler3,
ProcessCLRException, or __gxx_wasm_personality_v0 it returns true.

In WinEHPrepare::runOnFunction, if the personality function is not scoped, then
it returns false and WinEHPrepare does nothing to that function. There may be
other places that change their behaviour based in isScopedEHPersonality, but
that's the one that jumps out at me.

So here's my main complaint: the new instructions for dealing with windows
exception handling, catch* and cleanup*, are completely unusable (as far as I
can tell) if you're not running one of those personality functions, as LLVM
won't emit the data needed, and will just instead emit an (empty, as there are
no landingpads) DWARF exception table, like it was an Itanium EH target.

The documentation doesn't mention this at all, no errors or warnings are
generated by the verify passes. The only way to figure this out is to read the
source code. If there is a list of personality functions that is required for
the instructions to work at all, that should be mentioned; nowhere does it
indicate that you can't use your own, whenever it mentions the C++ runtime
functions it's usually prefaced with "for example" leading one to believe that
there are other options when there aren't.

https://llvm.org/docs/LangRef.html#i-catchpad

"The args correspond to whatever information the personality routine requires
to know if this is an appropriate handler for the exception." So, given that
there's a limited number of personality functions supported, and clang crashes
if the wrong arguments are given (in particular if the third parameter wasn't a
pointer to a pointer while using __CxxFrameHandler3), perhaps a general idea of
what each personality function needs is in order? If the response to that is
that's an implementation detail, who exactly is this documentation for? If
people are emitting catchpad, they're presumably implementing exception
handling, and need to know the 'implementation details'.

As for myself I've renamed our handler to __CxxFrameHandler3 and have found
several sources describing how that works internally (we want to avoid
depending on the CRT if we can help it) and will likely see if we can get our
personality function added to that list (maybe a mechanism for programattically
forcing the EHPersonality could be added?). But I can say that from the point
of view of someone implementing exception handling on Windows, this
documentation was less useful than just reading clang -emit-llvm, and I think
the documentation could be improved for the next person in a similar situation.

-- 
You are receiving this mail because:
You are on the CC list for the bug.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-bugs/attachments/20180802/8c6123ab/attachment-0001.html>