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.

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.

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.

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

Rework the definitions of the extern ABIs

9a2426c

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.

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

Add more ABI correspondence with other compilers

8da6ee3

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

Rework the definitions of the extern ABIs #2003

Are you sure you want to change the base?

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!

Uh oh!

ehuss commented Sep 17, 2025 •

edited

Loading

ChrisDenton commented Sep 17, 2025 •

edited by traviscross

Loading