Rework the definitions of the extern ABIs

[ehuss]

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]

@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]

Yes, that seems correct to me.

[ChrisDenton]

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.

[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]

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

[RalfJung]

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

[ehuss]

Updated, though I think you meant cdecl here?

[RalfJung]

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

[RalfJung]

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

[ehuss]

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

[RalfJung]

Seems worthwhile, doesn't it?

[RalfJung]

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

[ehuss]

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

[RalfJung]

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

[ehuss]

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?

[RalfJung]

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.

[ChrisDenton]

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]

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.

[rustbot]

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.