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

Update reference for target_feature_11. #1720

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

Update reference for target_feature_11. #1720

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3ced4db
Update reference for target_feature_11.
veluca93 Jan 24, 2025
ec933d3
Add target_feature to unsafety list
ehuss Feb 7, 2025
8b4a45c
Reward the `unsafe` block to be more general
ehuss Feb 7, 2025
e53d30b
Clean up the markdown
ehuss Feb 7, 2025
a28ead0
Rework the target_fature safety restrictions
ehuss Feb 7, 2025
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
51 changes: 38 additions & 13 deletions src/attributes/codegen.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,19 +69,45 @@ features. It uses the [_MetaListNameValueStr_] syntax with a single key of
```rust
# #[cfg(target_feature = "avx2")]
#[target_feature(enable = "avx2")]
unsafe fn foo_avx2() {}
fn foo_avx2() {}
```

r[attributes.codegen.target_feature.arch]
Each [target architecture] has a set of features that may be enabled. It is an
error to specify a feature for a target architecture that the crate is not
being compiled for.

r[attributes.codegen.target_feature.closures]
Closures defined within a `target_feature`-annotated function inherit the
attribute from the enclosing function.

r[attributes.codegen.target_feature.target-ub]
It is [undefined behavior] to call a function that is compiled with a feature
that is not supported on the current platform the code is running on, *except*
if the platform explicitly documents this to be safe.

r[attributes.codegen.target_feature.safety-restrictions]
Because of this, on many platforms the following restrictions apply:

- `#[target_feature]` functions (and closures that inherit the attribute)
can only be safely called within caller that enable all the `target_feature`s
that the callee enables.
Copy link
Contributor

Choose a reason for hiding this comment

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

Does this still exclude implicitly enabled features? If so, can this be clarified to state that it is only the explicitly listed features from the attribute on both sides, and does not consider implicit ones?

Copy link
Author

Choose a reason for hiding this comment

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

This does include implicitly enabled features on either side.
Although of course implicitly enabled features on the callee are enabled on the caller too if all the explicitly enabled features in the callee are enabled...

Do you think that is something that should be clarified?

Copy link
Contributor

Choose a reason for hiding this comment

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

Ah, ok. It looks like this changed in rust-lang/rust#128221 since the last time I looked at this.

I'd like to do a quick editorial pass, and I'll try to clarify this point. I'll try to get to that today.

- `#[target_feature]` functions (and closures that inherit the attribute)
can only be coerced to *safe* `fn` pointers in contexts that enable all the
`target_feature`s that the coercee enables.
- `#[target_feature]` functions *never* implement `Fn` traits, although
closures inheriting features from the enclosing function do.

Moreover, since Rust needs to be able to check the usage of `#[target_feature]`
functions at callsites to ensure safety, safe functions for which this check
would not be possible cannot be annotated with this attribute. This includes:

- `main`
- other special functions that allow safe functions such as `#[panic_handler]`
- safe trait methods
- safe default functions in traits


r[attributes.codegen.target_feature.inline]
Functions marked with `target_feature` are not inlined into a context that
does not support the given features. The `#[inline(always)]` attribute may not
Expand All @@ -98,8 +124,8 @@ r[attributes.codegen.target_feature.x86]


Executing code with unsupported features is undefined behavior on this platform.
Hence this platform requires that `#[target_feature]` is only applied to [`unsafe`
functions][unsafe function].
Hence on this platform usage of `#[target_feature]` functions follows the
[above restrictions][attributes.codegen.target_feature.safety-restrictions].

Feature | Implicitly Enables | Description
------------|--------------------|-------------------
Expand Down Expand Up @@ -166,8 +192,8 @@ r[attributes.codegen.target_feature.aarch64]
#### `aarch64`


This platform requires that `#[target_feature]` is only applied to [`unsafe`
functions][unsafe function].
On this platform the usage of `#[target_feature]` functions follows the
[above restrictions][attributes.codegen.target_feature.safety-restrictions].

Further documentation on these features can be found in the [ARM Architecture
Reference Manual], or elsewhere on [developer.arm.com].
Expand Down Expand Up @@ -231,8 +257,8 @@ r[attributes.codegen.target_feature.riscv]
#### `riscv32` or `riscv64`


This platform requires that `#[target_feature]` is only applied to [`unsafe`
functions][unsafe function].
On this platform the usage of `#[target_feature]` functions follows the
[above restrictions][attributes.codegen.target_feature.safety-restrictions].

Further documentation on these features can be found in their respective
specification. Many specifications are described in the [RISC-V ISA Manual] or
Expand Down Expand Up @@ -293,12 +319,11 @@ r[attributes.codegen.target_feature.wasm]
#### `wasm32` or `wasm64`


`#[target_feature]` may be used with both safe and
[`unsafe` functions][unsafe function] on Wasm platforms. It is impossible to
cause undefined behavior via the `#[target_feature]` attribute because
attempting to use instructions unsupported by the Wasm engine will fail at load
time without the risk of being interpreted in a way different from what the
compiler expected.
Safe `#[target_feature]` functions may always be used in safe contexts on Wasm
platforms. It is impossible to cause undefined behavior via the
`#[target_feature]` attribute because attempting to use instructions
unsupported by the Wasm engine will fail at load time without the risk of being
interpreted in a way different from what the compiler expected.

Feature | Implicitly Enables | Description
----------------------|---------------------|-------------------
Expand Down
Loading