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

Document the target_feature_11 feature #1181

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

Document the target_feature_11 feature #1181

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
54107ec
Document the `target_feature_11` feature
LeSeulArtichaut Mar 17, 2022
d00e6bb
Address review comments
LeSeulArtichaut Mar 2, 2023
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
47 changes: 32 additions & 15 deletions src/attributes/codegen.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,9 +53,8 @@ features. It uses the [_MetaListNameValueStr_] syntax with a single key of
`enable` whose value is a string of comma-separated feature names to enable.

```rust
# #[cfg(target_feature = "avx2")]
LeSeulArtichaut marked this conversation as resolved.
Show resolved Hide resolved
#[target_feature(enable = "avx2")]
unsafe fn foo_avx2() {}
fn foo_avx2() {}
```

Each [target architecture] has a set of features that may be enabled. It is an
Expand All @@ -66,20 +65,42 @@ 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.

Functions marked with `target_feature` are not inlined into a context that
does not support the given features. The `#[inline(always)]` attribute may not
be used with a `target_feature` attribute.
For this reason, a function marked with `target_feature` is unsafe, except in
a context that supports the given features. For example:
Copy link
Contributor

Choose a reason for hiding this comment

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

This doesn't really define what "a context that supports the given features" means. Can you add a little more detail here? For example, the RFC seems to contain more well-defined text as to exactly what this means. I'd like this to be able to address:

  • The context means functions that have at least the exact same target_features enabled.
  • This does not include implied features (that is, a fn with sse2 can't call a function with sse, even though sse2 implicitly enabled sse).
  • This does not include features enabled by default on the platform, or manually enabled as compiler flags.
  • Also include a short discussion of what is or is not allowed with trait definitions and impls.


```rust
# #[target_feature(enable = "avx2")]
LeSeulArtichaut marked this conversation as resolved.
Show resolved Hide resolved
# fn foo_avx2() {}

fn bar() {
// Calling `foo_avx2` here is unsafe, as we must ensure
// that AVX is available first.
unsafe {
foo_avx2();
}
}

#[target_feature(enable = "avx2")]
fn bar_avx2() {
// Calling `foo_avx2` here is safe.
foo_avx2();
|| foo_avx2();
}
```

Like unsafe functions, functions marked with `target_feature` cannot be
assigned to a safe function pointer and do not implement `FnOnce`.
LeSeulArtichaut marked this conversation as resolved.
Show resolved Hide resolved

Functions marked with `target_feature` are not inlined into a context unless
it supports the given features. The `#[inline(always)]` attribute may not
be used with `target_feature`.

### Available features

The following is a list of the available feature names.

#### `x86` or `x86_64`

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].

Feature | Implicitly Enables | Description
------------|--------------------|-------------------
`aes` | `sse2` | [AES] — Advanced Encryption Standard
Expand Down Expand Up @@ -135,9 +156,6 @@ Feature | Implicitly Enables | Description

#### `aarch64`

This platform requires that `#[target_feature]` is only applied to [`unsafe`
functions][unsafe function].

Further documentation on these features can be found in the [ARM Architecture
Reference Manual], or elsewhere on [developer.arm.com].

Expand Down Expand Up @@ -200,9 +218,8 @@ Feature | Implicitly Enables | Feature Name

#### `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
`#[target_feature]` may be called from a safe context 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.
Expand Down