Skip to content
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

Jump to bottom

ABI compatibility: remove section on target features #132136

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+6 −26
Open

ABI compatibility: remove section on target features #132136

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
32 changes: 6 additions & 26 deletions library/core/src/primitive_docs.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1743,20 +1743,18 @@ mod prim_ref {}
/// alignment, they might be passed in different registers and hence not be ABI-compatible.
///
/// ABI compatibility as a concern only arises in code that alters the type of function pointers,
/// code that imports functions via `extern` blocks, and in code that combines `#[target_feature]`
/// with `extern fn`. Altering the type of function pointers is wildly unsafe (as in, a lot more
/// unsafe than even [`transmute_copy`][mem::transmute_copy]), and should only occur in the most
/// exceptional circumstances. Most Rust code just imports functions via `use`. `#[target_feature]`
/// is also used rarely. So, most likely you do not have to worry about ABI compatibility.
/// and code that imports functions via `extern` blocks. Altering the type of function pointers is
/// wildly unsafe (as in, a lot more unsafe than even [`transmute_copy`][mem::transmute_copy]), and
/// should only occur in the most exceptional circumstances. Most Rust code just imports functions
/// via `use`. So, most likely you do not have to worry about ABI compatibility.
///
/// But assuming such circumstances, what are the rules? For this section, we are only considering
/// the ABI of direct Rust-to-Rust calls, not linking in general -- once functions are imported via
/// `extern` blocks, there are more things to consider that we do not go into here.
///
/// For two signatures to be considered *ABI-compatible*, they must use a compatible ABI string,
/// must take the same number of arguments, the individual argument types and the return types must
/// be ABI-compatible, and the target feature requirements must be met (see the subsection below for
/// the last point). The ABI string is declared via `extern "ABI" fn(...) -> ...`; note that
/// must take the same number of arguments, and the individual argument types and the return types
/// must be ABI-compatible. The ABI string is declared via `extern "ABI" fn(...) -> ...`; note that
/// `fn name(...) -> ...` implicitly uses the `"Rust"` ABI string and `extern fn name(...) -> ...`
/// implicitly uses the `"C"` ABI string.
///
Expand Down Expand Up @@ -1826,24 +1824,6 @@ mod prim_ref {}
/// Behavior since transmuting `None::<NonZero<i32>>` to `NonZero<i32>` violates the non-zero
/// requirement.
///
/// #### Requirements concerning target features
///
/// Under some conditions, the signature used by the caller and the callee can be ABI-incompatible
/// even if the exact same ABI string and types are being used. As an example, the
/// `std::arch::x86_64::__m256` type has a different `extern "C"` ABI when the `avx` feature is
/// enabled vs when it is not enabled.
///
/// Therefore, to ensure ABI compatibility when code using different target features is combined
/// (such as via `#[target_feature]`), we further require that one of the following conditions is
/// met:
///
/// - The function uses the `"Rust"` ABI string (which is the default without `extern`).
/// - Caller and callee are using the exact same set of target features. For the callee we consider
/// the features enabled (via `#[target_feature]` and `-C target-feature`/`-C target-cpu`) at the
/// declaration site; for the caller we consider the features enabled at the call site.
/// - Neither any argument nor the return value involves a SIMD type (`#[repr(simd)]`) that is not
/// behind a pointer indirection (i.e., `*mut __m256` is fine, but `(i32, __m256)` is not).
///
/// ### Trait implementations
///
/// In this documentation the shorthand `fn(T₁, T₂, …, Tₙ)` is used to represent non-variadic
Expand Down
Loading