Skip to content

document differences from pure hardware behavior #2176

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

Open
RalfJung wants to merge 1 commit into
base: main
Choose a base branch
from
+22 −2
Open

document differences from pure hardware behavior #2176

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
24 changes: 22 additions & 2 deletions crates/core_arch/src/core_arch_docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,12 @@ ensure at least a few guarantees are upheld:
typically done by ensuring that `#[cfg]` is used appropriately when using
this module.
* The CPU the program is currently running on supports the function being
called. For example it is unsafe to call an AVX2 function on a CPU that
called. For example, it is unsafe to call an AVX2 function on a CPU that
doesn't actually support AVX2.

As a result of the latter of these guarantees all intrinsics in this module
are `unsafe` and extra care needs to be taken when calling them!
are `unsafe` to call unless the caller enables the required target features,
and extra care needs to be taken when calling them!

# CPU Feature Detection

Expand Down Expand Up @@ -164,6 +165,25 @@ And with all that we should have a working program! This program will run
across all machines and it'll use the optimized AVX2 implementation on
machines where support is detected.

# Differences from pure hardware behavior

While the intrinsics in this module exist to expose particular instructions of the underlying
hardware, not all of them behave *exactly* like their corresponding instructions.

* Floating-point operations are subject to the usual [Rust semantics for NaN
values][nan].
* Operations that read or write the floating-point status register generally cannot be meaningfully
used because Rust makes no guarantee about when and where floating-point operations can be
executed. In particular, it is generally undefined behavior to change the default rounding or
exception behavior.
* Some operations have special memory-model effects that are incompatible with the Rust Abstract
Machine, which means they are subject to more strict requirements than they would be in an
assembly program. Most notably, this applies to [non-temporal ("streaming") stores on
x86][non-temporal].

[nan]: ../../core/primitive.f32.html#nan-bit-patterns
[non-temporal]: ../../core/arch/x86/fn._mm_sfence.html#safety-of-non-temporal-stores

# Ergonomics

It's important to note that using the `arch` module is not the easiest
Expand Down