std: update comments on gcc personality fn · model-checking/verify-rust-std@244d843 (original) (raw)
`@@ -98,11 +98,12 @@ cfg_if::cfg_if! {
`
98
98
` not(all(target_vendor = "apple", not(target_os = "watchos"))),
`
99
99
` not(target_os = "netbsd"),
`
100
100
`))] {
`
101
``
`-
// ARM EHABI personality routine.
`
102
``
`-
`
103
``
`-
//
`
104
``
`-
// Apple 32-bit ARM (but not watchOS) uses the default routine instead
`
105
``
`-
// since it uses SjLj unwinding.
`
``
101
`+
/// personality fn called by [ARM EHABI][armeabi-eh]
`
``
102
`+
///
`
``
103
`+
/// Apple 32-bit ARM (but not watchOS) uses the default routine instead
`
``
104
`+
/// since it uses "setjmp-longjmp" unwinding.
`
``
105
`+
///
`
``
106
`+
/// [armeabi-eh]: https://web.archive.org/web/20190728160938/https://infocenter.arm.com/help/topic/com.arm.doc.ihi0038b/IHI0038B_ehabi.pdf
`
106
107
` #[lang = "eh_personality"]
`
107
108
`unsafe extern "C" fn rust_eh_personality(
`
108
109
` state: uw::_Unwind_State,
`
`@@ -200,8 +201,8 @@ cfg_if::cfg_if! {
`
200
201
`}
`
201
202
`}
`
202
203
`} else {
`
203
``
`-
// Default personality routine, which is used directly on most targets
`
204
``
`-
// and indirectly on Windows x86_64 via SEH.
`
``
204
`+
/// Default personality routine, which is used directly on most targets
`
``
205
`+
/// and indirectly on Windows x86_64 and AArch64 via SEH.
`
205
206
`unsafe extern "C" fn rust_eh_personality_impl(
`
206
207
` version: c_int,
`
207
208
` actions: uw::_Unwind_Action,
`
`@@ -246,8 +247,12 @@ cfg_if::cfg_if! {
`
246
247
``
247
248
` cfg_if::cfg_if! {
`
248
249
`if #[cfg(all(windows, any(target_arch = "aarch64", target_arch = "x86_64"), target_env = "gnu"))] {
`
249
``
`-
// On x86_64 MinGW targets, the unwinding mechanism is SEH however the unwind
`
250
``
`-
// handler data (aka LSDA) uses GCC-compatible encoding.
`
``
250
`+
/// personality fn called by [Windows Structured Exception Handling][windows-eh]
`
``
251
`+
///
`
``
252
`+
/// On x86_64 and AArch64 MinGW targets, the unwinding mechanism is SEH,
`
``
253
`+
/// however the unwind handler data (aka LSDA) uses GCC-compatible encoding
`
``
254
`+
///
`
``
255
`+
/// [windows-eh]: https://learn.microsoft.com/en-us/cpp/cpp/structured-exception-handling-c-cpp?view=msvc-170
`
251
256
` #[lang = "eh_personality"]
`
252
257
` #[allow(nonstandard_style)]
`
253
258
`unsafe extern "C" fn rust_eh_personality(
`
`@@ -256,6 +261,9 @@ cfg_if::cfg_if! {
`
256
261
` contextRecord: *mut uw::CONTEXT,
`
257
262
` dispatcherContext: *mut uw::DISPATCHER_CONTEXT,
`
258
263
`) -> uw::EXCEPTION_DISPOSITION {
`
``
264
`+
// SAFETY: the cfg is still target_os = "windows" and target_env = "gnu",
`
``
265
`+
// which means that this is the correct function to call, passing our impl fn
`
``
266
`+
// as the callback which gets actually used
`
259
267
`unsafe {
`
260
268
` uw::_GCC_specific_handler(
`
261
269
` exceptionRecord,
`
`@@ -267,7 +275,19 @@ cfg_if::cfg_if! {
`
267
275
`}
`
268
276
`}
`
269
277
`} else {
`
270
``
`-
// The personality routine for most of our targets.
`
``
278
`+
/// personality fn called by [Itanium C++ ABI Exception Handling][itanium-eh]
`
``
279
`+
///
`
``
280
`+
/// The personality routine for most non-Windows targets. This will be called by
`
``
281
`+
/// the unwinding library:
`
``
282
`+
/// - "In the search phase, the framework repeatedly calls the personality routine,
`
``
283
`+
/// with the _UA_SEARCH_PHASE flag as described below, first for the current PC
`
``
284
`+
/// and register state, and then unwinding a frame to a new PC at each step..."
`
``
285
`+
/// - "If the search phase reports success, the framework restarts in the cleanup
`
``
286
`+
/// phase. Again, it repeatedly calls the personality routine, with the
`
``
287
`+
/// _UA_CLEANUP_PHASE flag as described below, first for the current PC and
`
``
288
`+
/// register state, and then unwinding a frame to a new PC at each step..."i
`
``
289
`+
///
`
``
290
`+
/// [itanium-eh]: https://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html
`
271
291
` #[lang = "eh_personality"]
`
272
292
`unsafe extern "C" fn rust_eh_personality(
`
273
293
` version: c_int,
`
`@@ -276,6 +296,8 @@ cfg_if::cfg_if! {
`
276
296
` exception_object: *mut uw::_Unwind_Exception,
`
277
297
` context: *mut uw::_Unwind_Context,
`
278
298
`) -> uw::_Unwind_Reason_Code {
`
``
299
`+
// SAFETY: the platform support must modify the cfg for the inner fn
`
``
300
`+
// if it needs something different than what is currently invoked.
`
279
301
`unsafe {
`
280
302
` rust_eh_personality_impl(
`
281
303
` version,
`