library/panic_unwind/src/seh.rs - rust - Git at Google

 //! Windows SEH
 //!
 //! On Windows (currently only on MSVC), the default exception handling
 //! mechanism is Structured Exception Handling (SEH). This is quite different
 //! than Dwarf-based exception handling (e.g., what other unix platforms use) in
 //! terms of compiler internals, so LLVM is required to have a good deal of
 //! extra support for SEH.
 //!
 //! In a nutshell, what happens here is:
 //!
 //! 1. The `panic` function calls the standard Windows function
 //!    `_CxxThrowException` to throw a C++-like exception, triggering the
 //!    unwinding process.
 //! 2. All landing pads generated by the compiler use the personality function
 //!    `__CxxFrameHandler3`, a function in the CRT, and the unwinding code in
 //!    Windows will use this personality function to execute all cleanup code on
 //!    the stack.
 //! 3. All compiler-generated calls to `invoke` have a landing pad set as a
 //!    `cleanuppad` LLVM instruction, which indicates the start of the cleanup
 //!    routine. The personality (in step 2, defined in the CRT) is responsible
 //!    for running the cleanup routines.
 //! 4. Eventually the "catch" code in the `try` intrinsic (generated by the
 //!    compiler) is executed and indicates that control should come back to
 //!    Rust. This is done via a `catchswitch` plus a `catchpad` instruction in
 //!    LLVM IR terms, finally returning normal control to the program with a
 //!    `catchret` instruction.
 //!
 //! Some specific differences from the gcc-based exception handling are:
 //!
 //! * Rust has no custom personality function, it is instead *always*
 //!   `__CxxFrameHandler3`. Additionally, no extra filtering is performed, so we
 //!   end up catching any C++ exceptions that happen to look like the kind we're
 //!   throwing. Note that throwing an exception into Rust is undefined behavior
 //!   anyway, so this should be fine.
 //! * We've got some data to transmit across the unwinding boundary,
 //!   specifically a `Box<dyn Any + Send>`. Like with Dwarf exceptions
 //!   these two pointers are stored as a payload in the exception itself. On
 //!   MSVC, however, there's no need for an extra heap allocation because the
 //!   call stack is preserved while filter functions are being executed. This
 //!   means that the pointers are passed directly to `_CxxThrowException` which
 //!   are then recovered in the filter function to be written to the stack frame
 //!   of the `try` intrinsic.
 //!
 //! [win64]: https://docs.microsoft.com/en-us/cpp/build/exception-handling-x64
 //! [llvm]: https://llvm.org/docs/ExceptionHandling.html#background-on-windows-exceptions

 #![allow(nonstandard_style)]

 use alloc::boxed::Box;
 use alloc::panicking::PanicPayload;
 use core::any::Any;
 use core::ffi::c_void;
 use core::mem::ManuallyDrop;

 // NOTE(nbdd0121): The `canary` field is part of stable ABI.
 #[repr(C)]
 struct Exception {
     // See `gcc.rs` on why this is present. We already have a static here so just use it.
     canary: *const _TypeDescriptor,

     // This needs to be an Option because we catch the exception by reference
     // and its destructor is executed by the C++ runtime. When we take the Box
     // out of the exception, we need to leave the exception in a valid state
     // for its destructor to run without double-dropping the Box.
     // We also construct this as None for copies of the exception.
     data: Option<Box<dyn Any + Send>>,
 }

 // The purpose of all this is to implement the `panic` function below through a
 // call to `_CxxThrowException`.
 //
 // This function takes two arguments. The first is a pointer to the data we're
 // passing in, which in this case is our trait object. Pretty easy to find! The
 // next, however, is more complicated. This is a pointer to a `_ThrowInfo`
 // structure, and it generally is just intended to just describe the exception
 // being thrown.
 //
 // Currently the definition of this type [1] is a little hairy, and the main
 // oddity (and difference from the online article) is that on 32-bit the
 // pointers are pointers but on 64-bit the pointers are expressed as 32-bit
 // offsets from the image base. It's not currently possible to create a relative
 // offset in const Rust code, so this is done using assembly with the `@IMGREL`
 // relocation.
 //
 // The maze of type definitions also closely follows what LLVM emits for this
 // sort of operation. For example, if you compile this C++ code on MSVC and emit
 // the LLVM IR:
 //
 //      #include <stdint.h>
 //
 //      struct rust_panic {
 //          rust_panic(const rust_panic&);
 //          ~rust_panic();
 //
 //          uint64_t x[2];
 //      };
 //
 //      void foo() {
 //          rust_panic a = {0, 1};
 //          throw a;
 //      }
 //
 // That's essentially what we're trying to emulate. Most of the constant values
 // below were just copied from LLVM,
 //
 // In any case, these structures are all constructed in a similar manner, and
 // it's just somewhat verbose for us.
 //
 // [1]: https://www.geoffchappell.com/studies/msvc/language/predefined/

 #[repr(C)]
 struct _TypeDescriptor {
     pub pVFTable: *const u8,
     pub spare: *mut u8,
     pub name: [u8; 11],
 }

 unsafe impl Sync for _TypeDescriptor {}

 // Note that we intentionally ignore name mangling rules here: we don't want C++
 // to be able to catch Rust panics by simply declaring a `struct rust_panic`.
 //
 // When modifying, make sure that the type name string exactly matches
 // the one used in `compiler/rustc_codegen_llvm/src/intrinsic.rs`.
 const TYPE_NAME: [u8; 11] = *b"rust_panic\0";

 unsafe extern "C" {
     // The leading `\x01` byte here is actually a magical signal to LLVM to
     // *not* apply any other mangling like prefixing with a `_` character.
     //
     // This symbol is the vtable used by C++'s `std::type_info`. Objects of type
     // `std::type_info`, type descriptors, have a pointer to this table. Type
     // descriptors are referenced by the C++ EH structures defined above and
     // that we construct below.
     #[link_name = "\x01??_7type_info@@6B@"]
     static TYPE_INFO_VTABLE: u8;
 }

 // This type descriptor is only used when throwing an exception. The catch part
 // is handled by the try intrinsic, which generates its own TypeDescriptor.
 //
 // This is fine since the MSVC runtime uses string comparison on the type name
 // to match TypeDescriptors rather than pointer equality.
 static TYPE_DESCRIPTOR: _TypeDescriptor = _TypeDescriptor {
     pVFTable: &raw const TYPE_INFO_VTABLE,
     spare: core::ptr::null_mut(),
     name: TYPE_NAME,
 };

 // Destructor used if the C++ code decides to capture the exception and drop it
 // without propagating it. The catch part of the try intrinsic will set the
 // first word of the exception object to 0 so that it is skipped by the
 // destructor.
 //
 // Note that x86 Windows uses the "thiscall" calling convention for C++ member
 // functions instead of the default "C" calling convention.
 //
 // The exception_copy function is a bit special here: it is invoked by the MSVC
 // runtime under a try/catch block and the panic that we generate here will be
 // used as the result of the exception copy. This is used by the C++ runtime to
 // support capturing exceptions with std::exception_ptr, which we can't support
 // because Box<dyn Any> isn't clonable. Thus we throw an exception without data,
 // which the C++ runtime will attempt to copy, which will once again fail, and
 // a std::bad_exception instance ends up in the std::exception_ptr instance.
 // The lack of data doesn't matter because the exception will never be rethrown
 // - it is purely used to signal to the C++ runtime that copying failed.
 macro_rules! define_cleanup {
     ($abi:tt $abi2:tt) => {
         unsafe extern $abi fn exception_cleanup(e: *mut Exception) {
             unsafe {
                 if let Exception { data: Some(b), .. } = e.read() {
                     drop(b);
                     super::__rust_drop_panic();
                 }
             }
         }
         unsafe extern $abi2 fn exception_copy(
             _dest: *mut Exception, _src: *mut Exception
         ) -> *mut Exception {
             unsafe {
                 throw_exception(None);
             }
         }
     }
 }
 cfg_select! {
     target_arch = "x86" => {
         define_cleanup!("thiscall" "thiscall-unwind");
     }
     _ => {
         define_cleanup!("C" "C-unwind");
     }
 }

 pub(crate) fn panic(data: &mut dyn PanicPayload) -> u32 {
     unsafe { throw_exception(Some(data.take_box())) }
 }

 unsafe fn throw_exception(data: Option<Box<dyn Any + Send>>) -> ! {
     // _CxxThrowException executes entirely on this stack frame, so there's no
     // need to otherwise transfer `data` to the heap. We just pass a stack
     // pointer to this function.
     //
     // The ManuallyDrop is needed here since we don't want Exception to be
     // dropped when unwinding. Instead it will be dropped by exception_cleanup
     // which is invoked by the C++ runtime.
     let mut exception = ManuallyDrop::new(Exception { canary: &raw const TYPE_DESCRIPTOR, data });

     unsafe extern "system-unwind" {
         fn _CxxThrowException(pExceptionObject: *mut c_void, pThrowInfo: *const u8) -> !;
     }

     #[cfg(target_arch = "x86")]
     macro_rules! imgrel {
         ($s:literal) => {
             concat!(".long ", $s)
         };
     }
     #[cfg(not(target_arch = "x86"))]
     macro_rules! imgrel {
         ($s:literal) => {
             concat!(".long ", $s, "@IMGREL")
         };
     }

     let throw_info: *const u8;
     unsafe {
         core::arch::asm!(
             cfg_select! { // let throw_info = &THROW_INFO;
                 target_arch = "x86" => {
                     "lea {}, [2f]"
                 }
                 target_arch = "x86_64" => {
                     "lea {}, [rip + 2f]"
                 }
                 target_arch = "arm" => {
                     concat!(
                         "movw {0}, :lower16:2f\n",
                         "movt {0}, :upper16:2f",
                     )
                 }
                 any(target_arch = "aarch64", target_arch = "arm64ec") => {
                     concat!(
                         "adrp {0}, 2f\n",
                         "add {0}, {0}, :lo12:2f",
                     )
                 }
             },
             ".pushsection .rdata,\"dr\"",
             ".p2align 2",
             "2:",                     // static THROW_INFO = _ThrowInfo {
             ".long 0",                //     attributes: 0,
             imgrel!("{cleanup}"),     //     pmfnUnwind: exception_cleanup,
             ".long 0",                //     pForwardCompat: ptr::null_mut(),
             imgrel!("3f"),            //     pCatchableTypeArray: &CATCHABLE_TYPE_ARRAY,
                                       // }
             "3:",                     // static CATCHABLE_TYPE_ARRAY = _CatchableTypeArray {
             ".long 1",                //     nCatchableTypes: 1,
             imgrel!("4f"),            //     arrayOfCatchableTypes: [&CATCHABLE_TYPE],
                                       // }
             "4:",                     // static CATCHABLE_TYPE = _CatchableType {
             ".long 0",                //     properties: 0,
             imgrel!("{type_desc}"),   //     pType: &TYPE_DESCRIPTOR,
                                       //     thisDisplacement: _PMD {
             ".long 0",                //         mdisp: 0,
             ".long -1",               //         pdisp: -1,
             ".long 0",                //         vdisp: 0,
                                       //     }
             ".long {exception_size}", //     sizeOrOffset: size_of::<Exception>(),
             imgrel!("{copy}"),        //     copyFunction: exception_copy,
             ".popsection",            // }
             out(reg) throw_info,
             cleanup = sym exception_cleanup,
             type_desc = sym TYPE_DESCRIPTOR,
             exception_size = const size_of::<Exception>(),
             copy = sym exception_copy,
             options(readonly, nostack),
         );
         _CxxThrowException((&raw mut exception).cast(), throw_info);
     }
 }

 pub(crate) unsafe fn cleanup(payload: *mut u8) -> Box<dyn Any + Send> {
     // A null payload here means that we got here from the catch (...) of
     // __rust_try. This happens when a non-Rust foreign exception is caught.
     if payload.is_null() {
         super::__rust_foreign_exception();
     }
     let exception = payload as *mut Exception;
     unsafe {
         let canary = (&raw const (*exception).canary).read();
         if !core::ptr::eq(canary, &raw const TYPE_DESCRIPTOR) {
             // A foreign Rust exception.
             super::__rust_foreign_exception();
         }
         (*exception).data.take().unwrap()
     }
 }
	//! Windows SEH
	//!
	//! On Windows (currently only on MSVC), the default exception handling
	//! mechanism is Structured Exception Handling (SEH). This is quite different
	//! than Dwarf-based exception handling (e.g., what other unix platforms use) in
	//! terms of compiler internals, so LLVM is required to have a good deal of
	//! extra support for SEH.
	//!
	//! In a nutshell, what happens here is:
	//!
	//! 1. The `panic` function calls the standard Windows function
	//! `_CxxThrowException` to throw a C++-like exception, triggering the
	//! unwinding process.
	//! 2. All landing pads generated by the compiler use the personality function
	//! `__CxxFrameHandler3`, a function in the CRT, and the unwinding code in
	//! Windows will use this personality function to execute all cleanup code on
	//! the stack.
	//! 3. All compiler-generated calls to `invoke` have a landing pad set as a
	//! `cleanuppad` LLVM instruction, which indicates the start of the cleanup
	//! routine. The personality (in step 2, defined in the CRT) is responsible
	//! for running the cleanup routines.
	//! 4. Eventually the "catch" code in the `try` intrinsic (generated by the
	//! compiler) is executed and indicates that control should come back to
	//! Rust. This is done via a `catchswitch` plus a `catchpad` instruction in
	//! LLVM IR terms, finally returning normal control to the program with a
	//! `catchret` instruction.
	//!
	//! Some specific differences from the gcc-based exception handling are:
	//!
	//! * Rust has no custom personality function, it is instead always
	//! `__CxxFrameHandler3`. Additionally, no extra filtering is performed, so we
	//! end up catching any C++ exceptions that happen to look like the kind we're
	//! throwing. Note that throwing an exception into Rust is undefined behavior
	//! anyway, so this should be fine.
	//! * We've got some data to transmit across the unwinding boundary,
	//! specifically a `Box<dyn Any + Send>`. Like with Dwarf exceptions
	//! these two pointers are stored as a payload in the exception itself. On
	//! MSVC, however, there's no need for an extra heap allocation because the
	//! call stack is preserved while filter functions are being executed. This
	//! means that the pointers are passed directly to `_CxxThrowException` which
	//! are then recovered in the filter function to be written to the stack frame
	//! of the `try` intrinsic.
	//!
	//! [win64]: https://docs.microsoft.com/en-us/cpp/build/exception-handling-x64
	//! [llvm]: https://llvm.org/docs/ExceptionHandling.html#background-on-windows-exceptions

	#![allow(nonstandard_style)]

	use alloc::boxed::Box;
	use alloc::panicking::PanicPayload;
	use core::any::Any;
	use core::ffi::c_void;
	use core::mem::ManuallyDrop;

	// NOTE(nbdd0121): The `canary` field is part of stable ABI.
	#[repr(C)]
	struct Exception {
	// See `gcc.rs` on why this is present. We already have a static here so just use it.
	canary: *const _TypeDescriptor,

	// This needs to be an Option because we catch the exception by reference
	// and its destructor is executed by the C++ runtime. When we take the Box
	// out of the exception, we need to leave the exception in a valid state
	// for its destructor to run without double-dropping the Box.
	// We also construct this as None for copies of the exception.
	data: Option<Box<dyn Any + Send>>,
	}

	// The purpose of all this is to implement the `panic` function below through a
	// call to `_CxxThrowException`.
	//
	// This function takes two arguments. The first is a pointer to the data we're
	// passing in, which in this case is our trait object. Pretty easy to find! The
	// next, however, is more complicated. This is a pointer to a `_ThrowInfo`
	// structure, and it generally is just intended to just describe the exception
	// being thrown.
	//
	// Currently the definition of this type [1] is a little hairy, and the main
	// oddity (and difference from the online article) is that on 32-bit the
	// pointers are pointers but on 64-bit the pointers are expressed as 32-bit
	// offsets from the image base. It's not currently possible to create a relative
	// offset in const Rust code, so this is done using assembly with the `@IMGREL`
	// relocation.
	//
	// The maze of type definitions also closely follows what LLVM emits for this
	// sort of operation. For example, if you compile this C++ code on MSVC and emit
	// the LLVM IR:
	//
	// #include <stdint.h>
	//
	// struct rust_panic {
	// rust_panic(const rust_panic&);
	// ~rust_panic();
	//
	// uint64_t x[2];
	// };
	//
	// void foo() {
	// rust_panic a = {0, 1};
	// throw a;
	// }
	//
	// That's essentially what we're trying to emulate. Most of the constant values
	// below were just copied from LLVM,
	//
	// In any case, these structures are all constructed in a similar manner, and
	// it's just somewhat verbose for us.
	//
	// [1]: https://www.geoffchappell.com/studies/msvc/language/predefined/

	#[repr(C)]
	struct _TypeDescriptor {
	pub pVFTable: *const u8,
	pub spare: *mut u8,
	pub name: [u8; 11],
	}

	unsafe impl Sync for _TypeDescriptor {}

	// Note that we intentionally ignore name mangling rules here: we don't want C++
	// to be able to catch Rust panics by simply declaring a `struct rust_panic`.
	//
	// When modifying, make sure that the type name string exactly matches
	// the one used in `compiler/rustc_codegen_llvm/src/intrinsic.rs`.
	const TYPE_NAME: [u8; 11] = *b"rust_panic\0";

	unsafe extern "C" {
	// The leading `\x01` byte here is actually a magical signal to LLVM to
	// not apply any other mangling like prefixing with a `_` character.
	//
	// This symbol is the vtable used by C++'s `std::type_info`. Objects of type
	// `std::type_info`, type descriptors, have a pointer to this table. Type
	// descriptors are referenced by the C++ EH structures defined above and
	// that we construct below.
	#[link_name = "\x01??_7type_info@@6B@"]
	static TYPE_INFO_VTABLE: u8;
	}

	// This type descriptor is only used when throwing an exception. The catch part
	// is handled by the try intrinsic, which generates its own TypeDescriptor.
	//
	// This is fine since the MSVC runtime uses string comparison on the type name
	// to match TypeDescriptors rather than pointer equality.
	static TYPE_DESCRIPTOR: _TypeDescriptor = _TypeDescriptor {
	pVFTable: &raw const TYPE_INFO_VTABLE,
	spare: core::ptr::null_mut(),
	name: TYPE_NAME,
	};

	// Destructor used if the C++ code decides to capture the exception and drop it
	// without propagating it. The catch part of the try intrinsic will set the
	// first word of the exception object to 0 so that it is skipped by the
	// destructor.
	//
	// Note that x86 Windows uses the "thiscall" calling convention for C++ member
	// functions instead of the default "C" calling convention.
	//
	// The exception_copy function is a bit special here: it is invoked by the MSVC
	// runtime under a try/catch block and the panic that we generate here will be
	// used as the result of the exception copy. This is used by the C++ runtime to
	// support capturing exceptions with std::exception_ptr, which we can't support
	// because Box<dyn Any> isn't clonable. Thus we throw an exception without data,
	// which the C++ runtime will attempt to copy, which will once again fail, and
	// a std::bad_exception instance ends up in the std::exception_ptr instance.
	// The lack of data doesn't matter because the exception will never be rethrown
	// - it is purely used to signal to the C++ runtime that copying failed.
	macro_rules! define_cleanup {
	($abi:tt $abi2:tt) => {
	unsafe extern $abi fn exception_cleanup(e: *mut Exception) {
	unsafe {
	if let Exception { data: Some(b), .. } = e.read() {
	drop(b);
	super::__rust_drop_panic();
	}
	}
	}
	unsafe extern $abi2 fn exception_copy(
	_dest: mut Exception, _src: mut Exception
	) -> *mut Exception {
	unsafe {
	throw_exception(None);
	}
	}
	}
	}
	cfg_select! {
	target_arch = "x86" => {
	define_cleanup!("thiscall" "thiscall-unwind");
	}
	_ => {
	define_cleanup!("C" "C-unwind");
	}
	}

	pub(crate) fn panic(data: &mut dyn PanicPayload) -> u32 {
	unsafe { throw_exception(Some(data.take_box())) }
	}

	unsafe fn throw_exception(data: Option<Box<dyn Any + Send>>) -> ! {
	// _CxxThrowException executes entirely on this stack frame, so there's no
	// need to otherwise transfer `data` to the heap. We just pass a stack
	// pointer to this function.
	//
	// The ManuallyDrop is needed here since we don't want Exception to be
	// dropped when unwinding. Instead it will be dropped by exception_cleanup
	// which is invoked by the C++ runtime.
	let mut exception = ManuallyDrop::new(Exception { canary: &raw const TYPE_DESCRIPTOR, data });

	unsafe extern "system-unwind" {
	fn _CxxThrowException(pExceptionObject: mut c_void, pThrowInfo: const u8) -> !;
	}

	#[cfg(target_arch = "x86")]
	macro_rules! imgrel {
	($s:literal) => {
	concat!(".long ", $s)
	};
	}
	#[cfg(not(target_arch = "x86"))]
	macro_rules! imgrel {
	($s:literal) => {
	concat!(".long ", $s, "@IMGREL")
	};
	}

	let throw_info: *const u8;
	unsafe {
	core::arch::asm!(
	cfg_select! { // let throw_info = &THROW_INFO;
	target_arch = "x86" => {
	"lea {}, [2f]"
	}
	target_arch = "x86_64" => {
	"lea {}, [rip + 2f]"
	}
	target_arch = "arm" => {
	concat!(
	"movw {0}, :lower16:2f\n",
	"movt {0}, :upper16:2f",
	)
	}
	any(target_arch = "aarch64", target_arch = "arm64ec") => {
	concat!(
	"adrp {0}, 2f\n",
	"add {0}, {0}, :lo12:2f",
	)
	}
	},
	".pushsection .rdata,\"dr\"",
	".p2align 2",
	"2:", // static THROW_INFO = _ThrowInfo {
	".long 0", // attributes: 0,
	imgrel!("{cleanup}"), // pmfnUnwind: exception_cleanup,
	".long 0", // pForwardCompat: ptr::null_mut(),
	imgrel!("3f"), // pCatchableTypeArray: &CATCHABLE_TYPE_ARRAY,
	// }
	"3:", // static CATCHABLE_TYPE_ARRAY = _CatchableTypeArray {
	".long 1", // nCatchableTypes: 1,
	imgrel!("4f"), // arrayOfCatchableTypes: [&CATCHABLE_TYPE],
	// }
	"4:", // static CATCHABLE_TYPE = _CatchableType {
	".long 0", // properties: 0,
	imgrel!("{type_desc}"), // pType: &TYPE_DESCRIPTOR,
	// thisDisplacement: _PMD {
	".long 0", // mdisp: 0,
	".long -1", // pdisp: -1,
	".long 0", // vdisp: 0,
	// }
	".long {exception_size}", // sizeOrOffset: size_of::<Exception>(),
	imgrel!("{copy}"), // copyFunction: exception_copy,
	".popsection", // }
	out(reg) throw_info,
	cleanup = sym exception_cleanup,
	type_desc = sym TYPE_DESCRIPTOR,
	exception_size = const size_of::<Exception>(),
	copy = sym exception_copy,
	options(readonly, nostack),
	);
	_CxxThrowException((&raw mut exception).cast(), throw_info);
	}
	}

	pub(crate) unsafe fn cleanup(payload: *mut u8) -> Box<dyn Any + Send> {
	// A null payload here means that we got here from the catch (...) of
	// __rust_try. This happens when a non-Rust foreign exception is caught.
	if payload.is_null() {
	super::__rust_foreign_exception();
	}
	let exception = payload as *mut Exception;
	unsafe {
	let canary = (&raw const (*exception).canary).read();
	if !core::ptr::eq(canary, &raw const TYPE_DESCRIPTOR) {
	// A foreign Rust exception.
	super::__rust_foreign_exception();
	}
	(*exception).data.take().unwrap()
	}
	}