docs: Add win64 calling convention, update doc

[richo]

Wikipedia suggests that windows on x64 has it's own calling convention (Supported by the fact that we implement it)

source: http://en.wikipedia.org/wiki/X86_calling_conventions#x86-64_calling_conventions

[alexcrichton]

I think that may mean that windows defines a calling convention for 64-bit, not that it necessarily uses it. We have it defined because it's an abi that can be used.

I don't think that it's the one that windows uses internally at least for kernel32.dll because our system calling convention currently maps to C for windows on 64-bit, and I've heard that it's working (instead of horribly dying).

I may be wrong though, do you think that the win64 calling convention is the predominant one on win64?

[richo]

That's the impression I get.

I'll grab some win64 binaries tomorrow and pull them apart, until then let's leave this.

[richo]

Though, if it turns out not to be used, we may want to create an alias for it for uefi, where it is absolutely used.

[klutzy]

Win64 defines its own calling convention, and it's the "C" calling convention. On win64, extern "C" is as same as extern "win64" - LLVM treats them equally.
(Yes, the actual detail of C calling convention depends on target architecture. For example, C calling convention on win32 differ from one on linux: #9205)

We have explicit notion of win64 calling convention because it may be used outside windows, notably in UEFI specification. (See also #10527 and Booting to Rust)

[richo]

That explains a lot (The actual usecase was a friend doing some uefi stuff, hence the lack of windows. I'll update the patch to mention win64 in the list.

I'm a little suss on using "C" as the example, when it's so nontrivial.

[richo]

Patch updated.