Rework the definitions of the extern ABIs

This updates the definitions of the extern ABIs to try to make them a
little clearer as to what they mean.

This also adds new statements about the equivalence of some ABIs
to the "C" ABI.

Author: ehuss

src/glossary.md

@@ -11,6 +11,13 @@ The alignment of a value specifies what addresses values are preferred to
 start at. Always a power of two. References to a value must be aligned.
 [More][alignment].
 
+### Application binary interface (ABI)
+
+An *application binary interface* (ABI) defines the interface for compiled code to interact with other compiled code. With [`extern` blocks] and [`extern fn`], *ABI strings* affect:
+
+- **Calling convention**: How function arguments are passed and values are returned (e.g., in registers or on the stack).
+- **Unwinding**: How stack unwinding is handled when a panic occurs. For example, the `"C-unwind"` ABI allows unwinding across the FFI boundary, while the `"C"` ABI does not.
+
 ### Arity
 
 Arity refers to the number of arguments a function or operator takes.
@@ -287,6 +294,8 @@ uninhabited type is "empty" in the sense that there are no values of the type. T
 example of an uninhabited type is the [never type] `!`, or an enum with no variants
 `enum Never { }`. Opposite of [Inhabited](#inhabited).
 
+[`extern` blocks]: items.extern
+[`extern fn`]: items.fn.extern
 [alignment]: type-layout.md#size-and-alignment
 [associated item]: #associated-item
 [attributes]: attributes.md

src/items/external-blocks.md

@@ -111,13 +111,16 @@ r[items.extern.abi.standard]
 The following ABI strings are supported on all platforms:
 
 r[items.extern.abi.rust]
-* `unsafe extern "Rust"` --- The default ABI when you write a normal `fn foo()` in any Rust code.
+* `unsafe extern "Rust"` --- The native calling convention for Rust functions and closures. This is the default when the function's ABI is not specified. The Rust ABI offers no stability guarantees.
 
 r[items.extern.abi.c]
-* `unsafe extern "C"` --- This is the same as `extern fn foo()`; whatever the default your C compiler supports.
+* `unsafe extern "C"` --- The "C" ABI attempts to match the default ABI chosen by the dominant C compiler for the target.
 
 r[items.extern.abi.system]
-* `unsafe extern "system"` --- Usually the same as `extern "C"`, except on Win32, in which case it's `"stdcall"`, or what you should use to link to the Windows API itself.
+* `unsafe extern "system"` --- This is equivalent to `extern "C"` except on Windows x86_32 where it is equivalent to `"stdcall"`.
+
+  > [!NOTE]
+  > As the correct underlying ABI on Windows is target-specific, it's best to use `extern "system"` when attempting to link Windows API functions that don't otherwise use a different ABI.
 
 r[items.extern.abi.unwind]
 * `extern "C-unwind"` and `extern "system-unwind"` --- Identical to `"C"` and `"system"`, respectively, but with [different behavior][unwind-behavior] when the callee unwinds (by panicking or throwing a C++ style exception).
@@ -126,33 +129,57 @@ r[items.extern.abi.platform]
 There are also some platform-specific ABI strings:
 
 r[items.extern.abi.cdecl]
-* `unsafe extern "cdecl"` --- The default for x86_32 C code.
+* `unsafe extern "cdecl"` --- The calling convention typically used with x86_32 C code.
   * Only available on x86_32 targets.
 
+  > [!NOTE]
+  > See <https://learn.microsoft.com/en-us/cpp/cpp/cdecl> and <https://en.wikipedia.org/wiki/X86_calling_conventions#cdecl> for more information.
+
 r[items.extern.abi.stdcall]
-* `unsafe extern "stdcall"` --- The default for the Win32 API on x86_32.
+* `unsafe extern "stdcall"` --- The calling convention typically used by the [Win32 API] on x86_32.
   * Only available on x86_32 targets.
 
+  > [!NOTE]
+  > See <https://learn.microsoft.com/en-us/cpp/cpp/stdcall> and <https://en.wikipedia.org/wiki/X86_calling_conventions#stdcall> for more information.
+
 r[items.extern.abi.win64]
-* `unsafe extern "win64"` --- The default for C code on x86_64 Windows.
+* `unsafe extern "win64"` --- The Windows x64 ABI.
   * Only available on x86_64 targets.
+  * "win64" is the same as the "C" ABI on Windows x86_64 targets.
+
+  > [!NOTE]
+  > See <https://learn.microsoft.com/en-us/cpp/build/x64-software-conventions> and <https://en.wikipedia.org/wiki/X86_calling_conventions#Microsoft_x64_calling_convention> for more information.
 
 r[items.extern.abi.sysv64]
-* `unsafe extern "sysv64"` --- The default for C code on non-Windows x86_64.
+* `unsafe extern "sysv64"` --- The System V ABI.
   * Only available on x86_64 targets.
+  * "sysv64" is the same as the "C" ABI on non-Windows x86_64 targets.
+
+  > [!NOTE]
+  > See <https://wiki.osdev.org/System_V_ABI> or <https://en.wikipedia.org/wiki/X86_calling_conventions#System_V_AMD64_ABI> for more information.
 
 r[items.extern.abi.aapcs]
-* `unsafe extern "aapcs"` --- The default for ARM.
+* `unsafe extern "aapcs"` --- The soft-float ABI for ARM.
   * Only available on ARM32 targets.
+  * "aapcs" is the same as the "C" ABI on soft-float ARM32.
+
+  > [!NOTE]
+  > See [Arm Procedure Call Standard](https://developer.arm.com/documentation/107656/0101/Getting-started-with-Armv8-M-based-systems/Procedure-Call-Standard-for-Arm-Architecture--AAPCS-) for more information.
 
 r[items.extern.abi.fastcall]
 * `unsafe extern "fastcall"` --- The `fastcall` ABI --- corresponds to MSVC's `__fastcall` and GCC and clang's `__attribute__((fastcall))`.
   * Only available on x86_32 targets.
 
+  > [!NOTE]
+  > See <https://learn.microsoft.com/en-us/cpp/cpp/fastcall> and <https://en.wikipedia.org/wiki/X86_calling_conventions#Microsoft_fastcall> for more information.
+
 r[items.extern.abi.thiscall]
-* `unsafe extern "thiscall"` --- The default for C++ member functions on x86_32 MSVC --- corresponds to MSVC's `__thiscall` and GCC and clang's `__attribute__((thiscall))`.
+* `unsafe extern "thiscall"` --- The calling convention typically used on C++ class member functions on x86_32 MSVC --- corresponds to MSVC's `__thiscall` and GCC and clang's `__attribute__((thiscall))`.
   * Only available on x86_32 targets.
 
+  > [!NOTE]
+  > See <https://en.wikipedia.org/wiki/X86_calling_conventions#thiscall> and <https://learn.microsoft.com/en-us/cpp/cpp/thiscall> for more information.
+
 r[items.extern.abi.efiapi]
 * `unsafe extern "efiapi"` --- The ABI used for [UEFI] functions.
   * Only available on x86 and ARM targets (32bit and 64bit).
@@ -476,4 +503,5 @@ restrictions as [regular function parameters].
 [statics]: static-items.md
 [unwind-behavior]: functions.md#unwinding
 [value namespace]: ../names/namespaces.md
+[win32 api]: https://learn.microsoft.com/en-us/windows/win32/api/
 [`link_ordinal`]: items.extern.attributes.link_ordinal