Skip to content

Fix ABI string docs in reference.md #34461

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 27, 2016
Merged

Fix ABI string docs in reference.md #34461

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dbe6a09
First commit, fix ABI string docs in reference.md
ubsan Jun 24, 2016
1e899fd
Add vectorcall and fastcall explanation
ubsan Jun 25, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 31 additions & 2 deletions src/doc/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1631,14 +1631,43 @@ the Rust ABI and the foreign ABI.
A number of [attributes](#ffi-attributes) control the behavior of external blocks.

By default external blocks assume that the library they are calling uses the
standard C "cdecl" ABI. Other ABIs may be specified using an `abi` string, as
shown here:
standard C ABI on the specific platform. Other ABIs may be specified using an
`abi` string, as shown here:

```ignore
// Interface to the Windows API
extern "stdcall" { }
```

There are three ABI strings which are cross-platform, and which all compilers
are guaranteed to support:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given the fact that there are no other rust compilers, it seems like we should just say "which are cross-platform". This wording suggests that other compilers exist.

Copy link
Contributor Author

@strega-nil strega-nil Jul 19, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They do? They're not finished, but they exist. (mrustc, grustc)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mrustc is the main one I know of.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nikomatsakis and the rest of @rust-lang/lang , are we comfortable saying that all compilers are guaranteed to support this? It feels like a strange thing to "guarantee".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is a requirement, not a guarantee - i.e., "which all compilers must support:"


* `extern "Rust"` -- The default ABI when you write a normal `fn foo()` in any
Rust code.
* `extern "C"` -- This is the same as `extern fn foo()`; whatever the default
your C compiler supports.
* `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

There are also some platform-specific ABI strings:

* `extern "cdecl"` -- The default for x86\_32 C code.
* `extern "stdcall"` -- The default for the Win32 API on x86\_32.
* `extern "win64"` -- The default for C code on x86\_64 Windows.
* `extern "aapcs"` -- The default for ARM.
* `extern "fastcall"` -- The `fastcall` ABI -- corresponds to MSVC's
`__fastcall` and GCC and clang's `__attribute__((fastcall))`
* `extern "vectorcall"` -- The `vectorcall` ABI -- corresponds to MSVC's
`__vectorcall` and clang's `__attribute__((vectorcall))`

Finally, there are some rustc-specific ABI strings:

* `extern "rust-intrinsic"` -- The ABI of rustc intrinsics.
* `extern "rust-call"` -- The ABI of the Fn::call trait functions.
* `extern "platform-intrinsic"` -- Specific platform intrinsics -- like, for
example, `sqrt` -- have this ABI. You should never have to deal with it.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sqrt? I thought that was a regular intrinsic. Also, a subset of the platform intrinsics is likely to be stabilized in some form, while the more general set of intrinsics will remain unstable indefinitely.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The simd crate, for example, uses platform-intrinsics.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ubsan what's your response to @eddyb here?


The `link` attribute allows the name of the library to be specified. When
specified the compiler will attempt to link against the native library of the
specified name.
Expand Down