3 //! On Windows (currently only on MSVC), the default exception handling
4 //! mechanism is Structured Exception Handling (SEH). This is quite different
5 //! than Dwarf-based exception handling (e.g., what other unix platforms use) in
6 //! terms of compiler internals, so LLVM is required to have a good deal of
7 //! extra support for SEH.
9 //! In a nutshell, what happens here is:
11 //! 1. The `panic` function calls the standard Windows function
12 //! `_CxxThrowException` to throw a C++-like exception, triggering the
13 //! unwinding process.
14 //! 2. All landing pads generated by the compiler use the personality function
15 //! `__CxxFrameHandler3`, a function in the CRT, and the unwinding code in
16 //! Windows will use this personality function to execute all cleanup code on
18 //! 3. All compiler-generated calls to `invoke` have a landing pad set as a
19 //! `cleanuppad` LLVM instruction, which indicates the start of the cleanup
20 //! routine. The personality (in step 2, defined in the CRT) is responsible
21 //! for running the cleanup routines.
22 //! 4. Eventually the "catch" code in the `try` intrinsic (generated by the
23 //! compiler) is executed and indicates that control should come back to
24 //! Rust. This is done via a `catchswitch` plus a `catchpad` instruction in
25 //! LLVM IR terms, finally returning normal control to the program with a
26 //! `catchret` instruction.
28 //! Some specific differences from the gcc-based exception handling are:
30 //! * Rust has no custom personality function, it is instead *always*
31 //! `__CxxFrameHandler3`. Additionally, no extra filtering is performed, so we
32 //! end up catching any C++ exceptions that happen to look like the kind we're
33 //! throwing. Note that throwing an exception into Rust is undefined behavior
34 //! anyway, so this should be fine.
35 //! * We've got some data to transmit across the unwinding boundary,
36 //! specifically a `Box<dyn Any + Send>`. Like with Dwarf exceptions
37 //! these two pointers are stored as a payload in the exception itself. On
38 //! MSVC, however, there's no need for an extra heap allocation because the
39 //! call stack is preserved while filter functions are being executed. This
40 //! means that the pointers are passed directly to `_CxxThrowException` which
41 //! are then recovered in the filter function to be written to the stack frame
42 //! of the `try` intrinsic.
44 //! [win64]: https://docs.microsoft.com/en-us/cpp/build/exception-handling-x64
45 //! [llvm]: https://llvm.org/docs/ExceptionHandling.html#background-on-windows-exceptions
47 #![allow(nonstandard_style)]
49 use alloc::boxed::Box;
51 use core::mem::{self, ManuallyDrop};
53 use libc::{c_int, c_uint, c_void};
55 // NOTE(nbdd0121): The `canary` field will be part of stable ABI after `c_unwind` stabilization.
58 // See `gcc.rs` on why this is present. We already have a static here so just use it.
59 canary: *const _TypeDescriptor,
61 // This needs to be an Option because we catch the exception by reference
62 // and its destructor is executed by the C++ runtime. When we take the Box
63 // out of the exception, we need to leave the exception in a valid state
64 // for its destructor to run without double-dropping the Box.
65 data: Option<Box<dyn Any + Send>>,
68 // First up, a whole bunch of type definitions. There's a few platform-specific
69 // oddities here, and a lot that's just blatantly copied from LLVM. The purpose
70 // of all this is to implement the `panic` function below through a call to
71 // `_CxxThrowException`.
73 // This function takes two arguments. The first is a pointer to the data we're
74 // passing in, which in this case is our trait object. Pretty easy to find! The
75 // next, however, is more complicated. This is a pointer to a `_ThrowInfo`
76 // structure, and it generally is just intended to just describe the exception
79 // Currently the definition of this type [1] is a little hairy, and the main
80 // oddity (and difference from the online article) is that on 32-bit the
81 // pointers are pointers but on 64-bit the pointers are expressed as 32-bit
82 // offsets from the `__ImageBase` symbol. The `ptr_t` and `ptr!` macro in the
83 // modules below are used to express this.
85 // The maze of type definitions also closely follows what LLVM emits for this
86 // sort of operation. For example, if you compile this C++ code on MSVC and emit
89 // #include <stdint.h>
91 // struct rust_panic {
92 // rust_panic(const rust_panic&);
99 // rust_panic a = {0, 1};
103 // That's essentially what we're trying to emulate. Most of the constant values
104 // below were just copied from LLVM,
106 // In any case, these structures are all constructed in a similar manner, and
107 // it's just somewhat verbose for us.
109 // [1]: https://www.geoffchappell.com/studies/msvc/language/predefined/
111 #[cfg(target_arch = "x86")]
114 pub type ptr_t = *mut u8;
118 core::ptr::null_mut()
126 #[cfg(not(target_arch = "x86"))]
129 pub type ptr_t = u32;
132 pub static __ImageBase: u8;
138 (($e as usize) - (&imp::__ImageBase as *const _ as usize)) as u32
144 pub struct _ThrowInfo {
145 pub attributes: c_uint,
146 pub pmfnUnwind: imp::ptr_t,
147 pub pForwardCompat: imp::ptr_t,
148 pub pCatchableTypeArray: imp::ptr_t,
152 pub struct _CatchableTypeArray {
153 pub nCatchableTypes: c_int,
154 pub arrayOfCatchableTypes: [imp::ptr_t; 1],
158 pub struct _CatchableType {
159 pub properties: c_uint,
160 pub pType: imp::ptr_t,
161 pub thisDisplacement: _PMD,
162 pub sizeOrOffset: c_int,
163 pub copyFunction: imp::ptr_t,
174 pub struct _TypeDescriptor {
175 pub pVFTable: *const u8,
180 // Note that we intentionally ignore name mangling rules here: we don't want C++
181 // to be able to catch Rust panics by simply declaring a `struct rust_panic`.
183 // When modifying, make sure that the type name string exactly matches
184 // the one used in `compiler/rustc_codegen_llvm/src/intrinsic.rs`.
185 const TYPE_NAME: [u8; 11] = *b"rust_panic\0";
187 static mut THROW_INFO: _ThrowInfo = _ThrowInfo {
190 pForwardCompat: ptr!(0),
191 pCatchableTypeArray: ptr!(0),
194 static mut CATCHABLE_TYPE_ARRAY: _CatchableTypeArray =
195 _CatchableTypeArray { nCatchableTypes: 1, arrayOfCatchableTypes: [ptr!(0)] };
197 static mut CATCHABLE_TYPE: _CatchableType = _CatchableType {
200 thisDisplacement: _PMD { mdisp: 0, pdisp: -1, vdisp: 0 },
201 sizeOrOffset: mem::size_of::<Exception>() as c_int,
202 copyFunction: ptr!(0),
206 // The leading `\x01` byte here is actually a magical signal to LLVM to
207 // *not* apply any other mangling like prefixing with a `_` character.
209 // This symbol is the vtable used by C++'s `std::type_info`. Objects of type
210 // `std::type_info`, type descriptors, have a pointer to this table. Type
211 // descriptors are referenced by the C++ EH structures defined above and
212 // that we construct below.
213 #[link_name = "\x01??_7type_info@@6B@"]
214 static TYPE_INFO_VTABLE: *const u8;
217 // This type descriptor is only used when throwing an exception. The catch part
218 // is handled by the try intrinsic, which generates its own TypeDescriptor.
220 // This is fine since the MSVC runtime uses string comparison on the type name
221 // to match TypeDescriptors rather than pointer equality.
222 static mut TYPE_DESCRIPTOR: _TypeDescriptor = _TypeDescriptor {
223 pVFTable: unsafe { &TYPE_INFO_VTABLE } as *const _ as *const _,
224 spare: core::ptr::null_mut(),
228 // Destructor used if the C++ code decides to capture the exception and drop it
229 // without propagating it. The catch part of the try intrinsic will set the
230 // first word of the exception object to 0 so that it is skipped by the
233 // Note that x86 Windows uses the "thiscall" calling convention for C++ member
234 // functions instead of the default "C" calling convention.
236 // The exception_copy function is a bit special here: it is invoked by the MSVC
237 // runtime under a try/catch block and the panic that we generate here will be
238 // used as the result of the exception copy. This is used by the C++ runtime to
239 // support capturing exceptions with std::exception_ptr, which we can't support
240 // because Box<dyn Any> isn't clonable.
241 macro_rules! define_cleanup {
242 ($abi:tt $abi2:tt) => {
243 unsafe extern $abi fn exception_cleanup(e: *mut Exception) {
244 if let Exception { data: Some(b), .. } = e.read() {
246 super::__rust_drop_panic();
249 unsafe extern $abi2 fn exception_copy(_dest: *mut Exception,
250 _src: *mut Exception)
252 panic!("Rust panics cannot be copied");
257 if #[cfg(target_arch = "x86")] {
258 define_cleanup!("thiscall" "thiscall-unwind");
260 define_cleanup!("C" "C-unwind");
264 pub unsafe fn panic(data: Box<dyn Any + Send>) -> u32 {
265 use core::intrinsics::atomic_store_seqcst;
267 // _CxxThrowException executes entirely on this stack frame, so there's no
268 // need to otherwise transfer `data` to the heap. We just pass a stack
269 // pointer to this function.
271 // The ManuallyDrop is needed here since we don't want Exception to be
272 // dropped when unwinding. Instead it will be dropped by exception_cleanup
273 // which is invoked by the C++ runtime.
274 let mut exception = ManuallyDrop::new(Exception { canary: &TYPE_DESCRIPTOR, data: Some(data) });
275 let throw_ptr = &mut exception as *mut _ as *mut _;
277 // This... may seems surprising, and justifiably so. On 32-bit MSVC the
278 // pointers between these structure are just that, pointers. On 64-bit MSVC,
279 // however, the pointers between structures are rather expressed as 32-bit
280 // offsets from `__ImageBase`.
282 // Consequently, on 32-bit MSVC we can declare all these pointers in the
283 // `static`s above. On 64-bit MSVC, we would have to express subtraction of
284 // pointers in statics, which Rust does not currently allow, so we can't
287 // The next best thing, then is to fill in these structures at runtime
288 // (panicking is already the "slow path" anyway). So here we reinterpret all
289 // of these pointer fields as 32-bit integers and then store the
290 // relevant value into it (atomically, as concurrent panics may be
291 // happening). Technically the runtime will probably do a nonatomic read of
292 // these fields, but in theory they never read the *wrong* value so it
293 // shouldn't be too bad...
295 // In any case, we basically need to do something like this until we can
296 // express more operations in statics (and we may never be able to).
298 &mut THROW_INFO.pmfnUnwind as *mut _ as *mut u32,
299 ptr!(exception_cleanup) as u32,
302 &mut THROW_INFO.pCatchableTypeArray as *mut _ as *mut u32,
303 ptr!(&CATCHABLE_TYPE_ARRAY as *const _) as u32,
306 &mut CATCHABLE_TYPE_ARRAY.arrayOfCatchableTypes[0] as *mut _ as *mut u32,
307 ptr!(&CATCHABLE_TYPE as *const _) as u32,
310 &mut CATCHABLE_TYPE.pType as *mut _ as *mut u32,
311 ptr!(&TYPE_DESCRIPTOR as *const _) as u32,
314 &mut CATCHABLE_TYPE.copyFunction as *mut _ as *mut u32,
315 ptr!(exception_copy) as u32,
318 extern "system-unwind" {
319 fn _CxxThrowException(pExceptionObject: *mut c_void, pThrowInfo: *mut u8) -> !;
322 _CxxThrowException(throw_ptr, &mut THROW_INFO as *mut _ as *mut _);
325 pub unsafe fn cleanup(payload: *mut u8) -> Box<dyn Any + Send> {
326 // A null payload here means that we got here from the catch (...) of
327 // __rust_try. This happens when a non-Rust foreign exception is caught.
328 if payload.is_null() {
329 super::__rust_foreign_exception();
331 let exception = payload as *mut Exception;
332 let canary = ptr::addr_of!((*exception).canary).read();
333 if !ptr::eq(canary, &TYPE_DESCRIPTOR) {
334 // A foreign Rust exception.
335 super::__rust_foreign_exception();
337 (*exception).data.take().unwrap()