Rework the definitions of the extern ABIs #2003

ehuss · 2025-09-17T03:23:20Z

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.

Fixes #1946.

ehuss · 2025-09-17T13:38:13Z

@ChrisDenton We rephrased the description of the "system" ABI, and were wondering if you could take a look to see if the new text was accurate and conveyed the right meaning.

@Amanieu or @ChrisDenton We made a few new claims in this edit about the "C" ABI. We were sure who to ask, but were wondering if you knew the answer. In particular it is specifying that:

"win64" is the same as the "C" ABI on Windows x86_64 targets
"sysv64" is the same as the "C" ABI on non-Windows x86_64 targets

Amanieu · 2025-09-17T13:58:21Z

Yes, that seems correct to me.

ChrisDenton · 2025-09-17T15:40:59Z

Should probably @workingjubilee and @RalfJung who are knowledgable in this area.

This looks good to me though rust-lang/rust#136946 will need to adjust the the Windows 32-bit documentation to note the varargs peculiarity.

src/items/external-blocks.md

RalfJung

This sounds right but I don't actually know that much about all these target-specific ABIs.

Not sure how I feel about linking to the Microsoft docs for some of these (even when they are not Microsoft-defined ABIs, or are they?), but I don't know a better place to link to either.

RalfJung · 2025-09-18T07:56:01Z

src/items/external-blocks.md


 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.


"attempts to match" is a bit... weak?^^

RalfJung · 2025-09-18T07:56:39Z

src/items/external-blocks.md

+* `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 attemping to link to the Windows API.


This isn't true for all of the Windows API though, some of it uses "C"...

Updated, though I think you meant cdecl here?

No I meant "C". "cdecl" is x86-32-only.

RalfJung · 2025-09-18T07:59:27Z

src/items/external-blocks.md

+
 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.


Does this correspond to __stdcall or __attribute__((stdcall)) or anything like that on any other compiler?

I believe the answer is "yes". Are you suggesting this should explicitly say that like the entry for fastcall does?

Seems worthwhile, doesn't it?

RalfJung · 2025-09-18T08:01:33Z

src/items/external-blocks.md


 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.


Does this correspond to __scdecl or __attribute__((cdecl)) or anything like that on any other compiler?

I believe the answer here is also "yes" (assuming the s is a typo).

RalfJung · 2025-09-18T08:02:16Z

src/items/external-blocks.md

+* `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.


Do clang/gcc/MSVC have attributes that correspond to our win64/sysv64?

I believe the answer is "kinda".

AFAIK, Microsoft's __cdecl is the same as our "win64" or "C" (and I believe clang/gcc also do the same).

I believe for "sysv64", the answer is "no" for MSVC, you cannot explicitly specify that on MSVC. It looks like clang and gcc use the attribute sysv_abi.

Are you suggesting that we should be more explicit about these equivalences?

AFAIK, Microsoft's __cdecl is the same as our "win64" or "C"

That's just a consequence of "C" being "win64" for them, right?

Do clang/gcc support explicitly using the win64 ABI somehow? That would be the most direct equivalent.

Are you suggesting that we should be more explicit about these equivalences?

We're very explicit about it in some cases but not others. That seemed odd.

It's truer to say that __cdecl, __fastcall, etc is ignored outside of x86_32. I don't believe MSVC has an explicit calling convention for arm64 or x86_64. It just ignores any calling convention other than __vector_call and thus uses the default. I guess you could claim that one of these ignored calling conventions is the "real" name for the calling convention on x64 or arm64 but I don't think it's particularly useful to do so.

ehuss · 2025-09-29T20:51:28Z

OK, I pushed up a change that tries to be more consistent with showing the equivalent attributes.

My homework for investigating this:

Primary sources are:

Clang: https://clang.llvm.org/docs/AttributeReference.html
LLVM: https://llvm.org/doxygen/namespacellvm_1_1CallingConv.html
GCC: https://gcc.gnu.org/onlinedocs/gcc/x86-Function-Attributes.html
Descriptions in wikipedia: https://en.wikipedia.org/wiki/X86_calling_conventions
Other links in the PR.

For the translation in rustc to LLVM, there are multiple places to look:

AbiMapping -- This is a first canonicalization of ABIs. Most ABIs have a clear translation ("Rust" is "Rust"). Some are erased at this stage (efiapi gets translated to various other ABIs based on the target).
llvm::CallConv -- Converts rustc's call convention to LLVM's.
LLVM CallingConv.h -- LLVM's definition of the different calling conventions.
Clang CallingConv -- How attributes to mapped to a calling convention.
Clang ClangCallConvToLLVMCallConv -- Converts clang's calling convention to LLVM.

Generally I tried to make sure that clang translation to LLVM is the same as rustc's.

cdecl:
- rustc -> CanonAbi::C -> llvm::CCallConv
- clang -> CC_C -> llvm::C
stdcall:
- rustc -> X86Call::Stdcall -> llvm::X86StdcallCallConv
- clang -> CC_X86StdCall -> llvm::X86_StdCall
win64:
- rustc -> X86Call::Win64 -> llvm::X86_64_Win64
- clang -> CC_Win64 -> llvm::Win64
sysv64:
- rustc -> X86Call::SysV64 -> llvm::X86_64_SysV
- clang -> CC_X86_64SysV -> llvm::X86_64_SysV
aapcs:
- rustc -> ArmCall::Aapcs -> llvm::ArmAapcsCallConv
- clang -> CC_AAPCS -> llvm::ARM_AAPCS
- Note: does not seem documented in GCC.
fastcall:
- rustc -> X86Call::Fastcall -> llvm::X86FastcallCallConv
- clang -> CC_X86FastCall -> llvm::X86_FastCall
thiscall:
- rustc -> X86Call::Thiscall -> llvm::X86_ThisCall
- clang -> CC_X86ThisCall -> llvm::X86_ThisCall
efiapi:
- rustc -> ArmCall::Aapcs | X86Call::Win64 | CanonAbi::C -> llvm (see above)
- clang: N/A? Maybe uses the EFIAPI macro.

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.

rustbot · 2025-10-07T23:57:41Z

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

Due to changes we've recently merged discussing the default ABI of an `extern` that doesn't specify one ("C"), the description of "Rust" being the default ABI for functions that followed immediately after this read as a bit odd. Let's revise this to clarify that "Rust" is the default ABI when `extern fn` is not used.

Some Windows API functions have an explicitly defined ABI. We were trying to suggest this with wording that was a bit subtle; let's spell it out explicitly.

For each of the ABIs, we have outbound links to documents with more details. For most of these, we display the URL, since these URLs are short and readable enough that it's probably more informative to just show them as compared to trying to describe the document. However, the URLs are still long enough that they look better as list items, so let's switch to doing it that way.

When using the "C" ABI, do we "match" the default ABI chosen by the dominant C compiler for the target or do we "attempt" to match it? Tough question. There are believed to be some exceptions in current behavior. However, in the Reference, we generally state things in terms of what the consensus is on how they should be and then note the bugs, so let's do that here. We'll just say that we "match" it.

ehuss force-pushed the rewrite-abi-defs branch from 2c44aa0 to 094e2b3 Compare September 17, 2025 03:27

ehuss mentioned this pull request Sep 17, 2025

fix aapcs ABI docs, and state where which ABIs are available #1948

Closed

ChrisDenton reviewed Sep 17, 2025

View reviewed changes

src/items/external-blocks.md Outdated Show resolved Hide resolved

ehuss force-pushed the rewrite-abi-defs branch from 094e2b3 to 527bc1a Compare September 17, 2025 20:49

RalfJung reviewed Sep 18, 2025

View reviewed changes

ehuss force-pushed the rewrite-abi-defs branch from 527bc1a to 9a2426c Compare September 22, 2025 14:42

ehuss marked this pull request as ready for review September 29, 2025 20:52

rustbot added the S-waiting-on-review Status: The marked PR is awaiting review from a maintainer label Sep 29, 2025

This comment has been minimized.

Sign in to view

ehuss force-pushed the rewrite-abi-defs branch from 8da6ee3 to d0fce21 Compare October 7, 2025 21:17

This comment has been minimized.

Sign in to view

ehuss added 2 commits October 7, 2025 23:57

Rework the definitions of the extern ABIs

4047870

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.

Add more ABI correspondence with other compilers

e8969f7

traviscross force-pushed the rewrite-abi-defs branch from d0fce21 to e8969f7 Compare October 7, 2025 23:57

traviscross added 4 commits October 8, 2025 00:21

Clarify about Windows functions with explicit ABI

5ef9f4f

Some Windows API functions have an explicitly defined ABI. We were trying to suggest this with wording that was a bit subtle; let's spell it out explicitly.

traviscross approved these changes Oct 8, 2025

View reviewed changes

traviscross enabled auto-merge October 8, 2025 01:39

traviscross added this pull request to the merge queue Oct 8, 2025

Merged via the queue into rust-lang:master with commit 053c511 Oct 8, 2025
5 checks passed

rustbot removed the S-waiting-on-review Status: The marked PR is awaiting review from a maintainer label Oct 8, 2025

Rework the definitions of the extern ABIs #2003

Rework the definitions of the extern ABIs #2003

Uh oh!

Conversation

ehuss commented Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ehuss commented Sep 17, 2025

Uh oh!

Amanieu commented Sep 17, 2025

Uh oh!

ChrisDenton commented Sep 17, 2025 • edited by traviscross Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

RalfJung left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ehuss commented Sep 29, 2025

Uh oh!

This comment has been minimized.

This comment has been minimized.

rustbot commented Oct 7, 2025

Uh oh!

Uh oh!

Uh oh!

ehuss commented Sep 17, 2025 •

edited

Loading

ChrisDenton commented Sep 17, 2025 •

edited by traviscross

Loading