1 // Copyright 2015 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
13 //! On Windows (currently only on MSVC), the default exception handling
14 //! mechanism is Structured Exception Handling (SEH). This is quite different
15 //! than Dwarf-based exception handling (e.g. what other unix platforms use) in
16 //! terms of compiler internals, so LLVM is required to have a good deal of
17 //! extra support for SEH.
19 //! In a nutshell, what happens here is:
21 //! 1. The `panic` function calls the standard Windows function
22 //! `_CxxThrowException` to throw a C++-like exception, triggering the
23 //! unwinding process.
24 //! 2. All landing pads generated by the compiler use the personality function
25 //! `__CxxFrameHandler3`, a function in the CRT, and the unwinding code in
26 //! Windows will use this personality function to execute all cleanup code on
28 //! 3. All compiler-generated calls to `invoke` have a landing pad set as a
29 //! `cleanuppad` LLVM instruction, which indicates the start of the cleanup
30 //! routine. The personality (in step 2, defined in the CRT) is responsible
31 //! for running the cleanup routines.
32 //! 4. Eventually the "catch" code in the `try` intrinsic (generated by the
33 //! compiler) is executed and indicates that control should come back to
34 //! Rust. This is done via a `catchswitch` plus a `catchpad` instruction in
35 //! LLVM IR terms, finally returning normal control to the program with a
36 //! `catchret` instruction.
38 //! Some specific differences from the gcc-based exception handling are:
40 //! * Rust has no custom personality function, it is instead *always*
41 //! `__CxxFrameHandler3`. Additionally, no extra filtering is performed, so we
42 //! end up catching any C++ exceptions that happen to look like the kind we're
43 //! throwing. Note that throwing an exception into Rust is undefined behavior
44 //! anyway, so this should be fine.
45 //! * We've got some data to transmit across the unwinding boundary,
46 //! specifically a `Box<Any + Send>`. Like with Dwarf exceptions
47 //! these two pointers are stored as a payload in the exception itself. On
48 //! MSVC, however, there's no need for an extra heap allocation because the
49 //! call stack is preserved while filter functions are being executed. This
50 //! means that the pointers are passed directly to `_CxxThrowException` which
51 //! are then recovered in the filter function to be written to the stack frame
52 //! of the `try` intrinsic.
54 //! [win64]: http://msdn.microsoft.com/en-us/library/1eyas8tf.aspx
55 //! [llvm]: http://llvm.org/docs/ExceptionHandling.html#background-on-windows-exceptions
58 #![allow(private_no_mangle_fns)]
60 use alloc
::boxed
::Box
;
66 use libc
::{c_int, c_uint}
;
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
92 // uint64_t a[2] = {0, 1};
96 // That's essentially what we're trying to emulate. Most of the constant values
97 // below were just copied from LLVM, I'm at least not 100% sure what's going on
98 // everywhere. For example the `.PA_K\0` and `.PEA_K\0` strings below (stuck in
99 // the names of a few of these) I'm not actually sure what they do, but it seems
100 // to mirror what LLVM does!
102 // In any case, these structures are all constructed in a similar manner, and
103 // it's just somewhat verbose for us.
105 // [1]: http://www.geoffchappell.com/studies/msvc/language/predefined/
107 #[cfg(target_arch = "x86")]
110 pub type ptr_t
= *mut u8;
111 pub const OFFSET
: i32 = 4;
113 pub const NAME1
: [u8; 7] = [b'
.'
, b'P'
, b'A'
, b'_'
, b'K'
, 0, 0];
114 pub const NAME2
: [u8; 7] = [b'
.'
, b'P'
, b'A'
, b'X'
, 0, 0, 0];
117 (0) => (0 as *mut u8);
118 ($e
:expr
) => ($e
as *mut u8);
122 #[cfg(target_arch = "x86_64")]
125 pub type ptr_t
= u32;
126 pub const OFFSET
: i32 = 8;
128 pub const NAME1
: [u8; 7] = [b'
.'
, b'P'
, b'E'
, b'A'
, b'_'
, b'K'
, 0];
129 pub const NAME2
: [u8; 7] = [b'
.'
, b'P'
, b'E'
, b'A'
, b'X'
, 0, 0];
132 pub static __ImageBase
: u8;
138 (($e
as usize) - (&imp
::__ImageBase
as *const _
as usize)) as u32
144 pub struct _ThrowInfo
{
145 pub attribues
: c_uint
,
146 pub pnfnUnwind
: 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
; 2],
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 copy_function
: imp
::ptr_t
,
174 pub struct _TypeDescriptor
{
175 pub pVFTable
: *const u8,
180 static mut THROW_INFO
: _ThrowInfo
= _ThrowInfo
{
183 pForwardCompat
: ptr
!(0),
184 pCatchableTypeArray
: ptr
!(0),
187 static mut CATCHABLE_TYPE_ARRAY
: _CatchableTypeArray
= _CatchableTypeArray
{
189 arrayOfCatchableTypes
: [ptr
!(0), ptr
!(0)],
192 static mut CATCHABLE_TYPE1
: _CatchableType
= _CatchableType
{
195 thisDisplacement
: _PMD
{
200 sizeOrOffset
: imp
::OFFSET
,
201 copy_function
: ptr
!(0),
204 static mut CATCHABLE_TYPE2
: _CatchableType
= _CatchableType
{
207 thisDisplacement
: _PMD
{
212 sizeOrOffset
: imp
::OFFSET
,
213 copy_function
: ptr
!(0),
217 // The leading `\x01` byte here is actually a magical signal to LLVM to
218 // *not* apply any other mangling like prefixing with a `_` character.
220 // This symbol is the vtable used by C++'s `std::type_info`. Objects of type
221 // `std::type_info`, type descriptors, have a pointer to this table. Type
222 // descriptors are referenced by the C++ EH structures defined above and
223 // that we construct below.
224 #[link_name = "\x01??_7type_info@@6B@"]
225 static TYPE_INFO_VTABLE
: *const u8;
228 // We use #[lang = "msvc_try_filter"] here as this is the type descriptor which
229 // we'll use in LLVM's `catchpad` instruction which ends up also being passed as
230 // an argument to the C++ personality function.
232 // Again, I'm not entirely sure what this is describing, it just seems to work.
233 #[cfg_attr(not(test), lang = "msvc_try_filter")]
234 static mut TYPE_DESCRIPTOR1
: _TypeDescriptor
= _TypeDescriptor
{
235 pVFTable
: unsafe { &TYPE_INFO_VTABLE }
as *const _
as *const _
,
240 static mut TYPE_DESCRIPTOR2
: _TypeDescriptor
= _TypeDescriptor
{
241 pVFTable
: unsafe { &TYPE_INFO_VTABLE }
as *const _
as *const _
,
246 pub unsafe fn panic(data
: Box
<Any
+ Send
>) -> u32 {
247 use core
::intrinsics
::atomic_store
;
249 // _CxxThrowException executes entirely on this stack frame, so there's no
250 // need to otherwise transfer `data` to the heap. We just pass a stack
251 // pointer to this function.
253 // The first argument is the payload being thrown (our two pointers), and
254 // the second argument is the type information object describing the
255 // exception (constructed above).
256 let ptrs
= mem
::transmute
::<_
, raw
::TraitObject
>(data
);
257 let mut ptrs
= [ptrs
.data
as u64, ptrs
.vtable
as u64];
258 let mut ptrs_ptr
= ptrs
.as_mut_ptr();
260 // This... may seems surprising, and justifiably so. On 32-bit MSVC the
261 // pointers between these structure are just that, pointers. On 64-bit MSVC,
262 // however, the pointers between structures are rather expressed as 32-bit
263 // offsets from `__ImageBase`.
265 // Consequently, on 32-bit MSVC we can declare all these pointers in the
266 // `static`s above. On 64-bit MSVC, we would have to express subtraction of
267 // pointers in statics, which Rust does not currently allow, so we can't
270 // The next best thing, then is to fill in these structures at runtime
271 // (panicking is already the "slow path" anyway). So here we reinterpret all
272 // of these pointer fields as 32-bit integers and then store the
273 // relevant value into it (atomically, as concurrent panics may be
274 // happening). Technically the runtime will probably do a nonatomic read of
275 // these fields, but in theory they never read the *wrong* value so it
276 // shouldn't be too bad...
278 // In any case, we basically need to do something like this until we can
279 // express more operations in statics (and we may never be able to).
280 atomic_store(&mut THROW_INFO
.pCatchableTypeArray
as *mut _
as *mut u32,
281 ptr
!(&CATCHABLE_TYPE_ARRAY
as *const _
) as u32);
282 atomic_store(&mut CATCHABLE_TYPE_ARRAY
.arrayOfCatchableTypes
[0] as *mut _
as *mut u32,
283 ptr
!(&CATCHABLE_TYPE1
as *const _
) as u32);
284 atomic_store(&mut CATCHABLE_TYPE_ARRAY
.arrayOfCatchableTypes
[1] as *mut _
as *mut u32,
285 ptr
!(&CATCHABLE_TYPE2
as *const _
) as u32);
286 atomic_store(&mut CATCHABLE_TYPE1
.pType
as *mut _
as *mut u32,
287 ptr
!(&TYPE_DESCRIPTOR1
as *const _
) as u32);
288 atomic_store(&mut CATCHABLE_TYPE2
.pType
as *mut _
as *mut u32,
289 ptr
!(&TYPE_DESCRIPTOR2
as *const _
) as u32);
291 c
::_CxxThrowException(&mut ptrs_ptr
as *mut _
as *mut _
,
292 &mut THROW_INFO
as *mut _
as *mut _
);
296 pub fn payload() -> [u64; 2] {
300 pub unsafe fn cleanup(payload
: [u64; 2]) -> Box
<Any
+ Send
> {
301 mem
::transmute(raw
::TraitObject
{
302 data
: payload
[0] as *mut _
,
303 vtable
: payload
[1] as *mut _
,
307 // This is required by the compiler to exist (e.g. it's a lang item), but
308 // it's never actually called by the compiler because __C_specific_handler
309 // or _except_handler3 is the personality function that is always used.
310 // Hence this is just an aborting stub.
311 #[lang = "eh_personality"]
313 fn rust_eh_personality() {
314 unsafe { ::core::intrinsics::abort() }