mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rollup merge of #132136 - RalfJung:target-feature-abi-compat, r=Mark-Simulacrum

Browse Source 
ABI compatibility: remove section on target features

Once https://github.com/rust-lang/rust/pull/127731 lands, we will properly diagnose ABI issues caused by target feature mismatch (at least on tier 1 targets). So I'd say we can remove the corresponding part of the docs here -- this is now something the compiler can take care of, so programmers don't need to be concerned. For now this is just a lint, but that's just a transition period, like in prior cases where we fix I-unsound bugs by adding a new check that goes through the "future incompatibility" stages. We have decided that it's actually a bug that we have ABI risks around target features, and we shouldn't document that bug as-if it was intended behavior.

Cc `@rust-lang/opsem` `@chorman0773` `@veluca93`
This commit is contained in:
Matthias Krüger 2024-11-10 10:09:52 +01:00 committed by GitHub
commit 94cc01af15
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 6 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
library/core/src/primitive_docs.rs
View File

@ -1746,11 +1746,10 @@ mod prim_ref {}
/// alignment, they might be passed in different registers and hence not be ABI-compatible. /// 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, /// 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]` /// and code that imports functions via `extern` blocks. Altering the type of function pointers is
/// with `extern fn`. Altering the type of function pointers is wildly unsafe (as in, a lot more /// wildly unsafe (as in, a lot more unsafe than even [`transmute_copy`][mem::transmute_copy]), and
/// unsafe than even [`transmute_copy`][mem::transmute_copy]), and should only occur in the most /// should only occur in the most exceptional circumstances. Most Rust code just imports functions
/// exceptional circumstances. Most Rust code just imports functions via `use`. `#[target_feature]` /// via `use`. So, most likely you do not have to worry about ABI compatibility.
/// is also used rarely. 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 /// But assuming such circumstances, what are the rules? For this section, we are only considering
/// the ABI of direct Rust-to-Rust calls (with both definition and callsite visible to the /// the ABI of direct Rust-to-Rust calls (with both definition and callsite visible to the
@ -1762,9 +1761,8 @@ mod prim_ref {}
/// types from `core::ffi` or `libc`**. /// types from `core::ffi` or `libc`**.
/// ///
/// For two signatures to be considered *ABI-compatible*, they must use a compatible ABI string, /// 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 /// must take the same number of arguments, and the individual argument types and the return types
/// be ABI-compatible, and the target feature requirements must be met (see the subsection below for /// must be ABI-compatible. The ABI string is declared via `extern "ABI" fn(...) -> ...`; note that
/// the last point). The ABI string is declared via `extern "ABI" fn(...) -> ...`; note that
/// `fn name(...) -> ...` implicitly uses the `"Rust"` ABI string and `extern fn name(...) -> ...` /// `fn name(...) -> ...` implicitly uses the `"Rust"` ABI string and `extern fn name(...) -> ...`
/// implicitly uses the `"C"` ABI string. /// implicitly uses the `"C"` ABI string.
/// ///
@ -1834,24 +1832,6 @@ mod prim_ref {}
/// Behavior since transmuting `None::<NonZero<i32>>` to `NonZero<i32>` violates the non-zero /// Behavior since transmuting `None::<NonZero<i32>>` to `NonZero<i32>` violates the non-zero
/// requirement. /// 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 /// ### Trait implementations
/// ///
/// In this documentation the shorthand `fn(T₁, T₂, …, Tₙ)` is used to represent non-variadic /// In this documentation the shorthand `fn(T₁, T₂, …, Tₙ)` is used to represent non-variadic