Skip to content

Update target_feature to use the attribute template #1910

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
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Update target_feature to use the attribute template #1910

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8fc864d
Unwrap target_feature
ehuss Jun 21, 2025
3b3a7b8
Move example to an example block
ehuss Jun 22, 2025
1d719db
Update target_feature to use the attribute template
ehuss Jun 22, 2025
d001f54
Move target_feature remarks to note blocks
ehuss Jun 22, 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
124 changes: 58 additions & 66 deletions src/attributes/codegen.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,38 +93,68 @@ r[attributes.codegen.target_feature]
## The `target_feature` attribute

r[attributes.codegen.target_feature.intro]
The *`target_feature` [attribute]* may be applied to a function to
enable code generation of that function for specific platform architecture
features. It uses the [MetaListNameValueStr] syntax with a single key of
`enable` whose value is a string of comma-separated feature names to enable.
The *`target_feature` [attribute]* may be applied to a function to enable code generation of that function for specific platform architecture features.

```rust
# #[cfg(target_feature = "avx2")]
#[target_feature(enable = "avx2")]
fn foo_avx2() {}
> [!EXAMPLE]
> ```rust
> # #[cfg(target_feature = "avx2")]
> #[target_feature(enable = "avx2")]
> fn foo_avx2() {}
> ```

> [!NOTE]
> See the [`target_feature` conditional compilation option] for selectively enabling or disabling compilation of code based on compile-time settings. Note that this option is not affected by the `target_feature` attribute, and is only driven by the features enabled for the entire crate.
>
> See the [`is_x86_feature_detected`] or [`is_aarch64_feature_detected`] macros in the standard library for runtime feature detection on these platforms.

> [!NOTE]
> `rustc` has a default set of features enabled for each target and CPU. The CPU may be chosen with the [`-C target-cpu`] flag. Individual features may be enabled or disabled for an entire crate with the [`-C target-feature`] flag.

r[attributes.codegen.target_feature.syntax]
The syntax for the `target_feature` attribute is:

```grammar,attributes
@root TargetFeatureAttribute ->
`target_feature` `(` `enable` `=` (STRING_LITERAL | RAW_STRING_LITERAL) `)`
```

The given string is a comma-separated list of feature names to enable. See [available features](#available-features) for the list of features that are available.

r[attributes.codegen.target_feature.allowed-positions]
The `target_feature` may only be applied to:

- [Free functions][items.fn]
- [Inherent associated functions][items.associated.fn]
- [Trait impl functions][items.impl.trait]
- [Trait definition functions][items.traits] with a body

It is not allowed on the following places:

- [the `main` function][crate.main]
- a [`panic_handler` function][panic.panic_handler]
- safe trait methods
- safe default functions in traits

> [!NOTE]
> `rustc` currently warns on some positions where it is ignored, but this may become an error in the future.

r[attributes.codegen.target_feature.duplicates]
If the `target_feature` attribute is specified multiple times on an item, then the union of all the specified features are enabled.

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.
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.
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.
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]
The following restrictions apply unless otherwise specified by the platform rules below:

- Safe `#[target_feature]` functions (and closures that inherit the attribute) can only be safely called within a caller that enables all the `target_feature`s that the callee enables.
This restriction does not apply in an `unsafe` context.
- Safe `#[target_feature]` functions (and closures that inherit the attribute) can only be coerced to *safe* function pointers in contexts that enable all the `target_feature`s that the coercee enables.
This restriction does not apply to `unsafe` function pointers.
- Safe `#[target_feature]` functions (and closures that inherit the attribute) can only be safely called within a caller that enables all the `target_feature`s that the callee enables. This restriction does not apply in an `unsafe` context.
- Safe `#[target_feature]` functions (and closures that inherit the attribute) can only be coerced to *safe* function pointers in contexts that enable all the `target_feature`s that the coercee enables. This restriction does not apply to `unsafe` function pointers.

Implicitly enabled features are included in this rule. For example an `sse2` function can call ones marked with `sse`.

Expand Down Expand Up @@ -160,18 +190,8 @@ fn bar_sse2() {
r[attributes.codegen.target_feature.fn-traits]
A function with a `#[target_feature]` attribute *never* implements the `Fn` family of traits, although closures inheriting features from the enclosing function do.

r[attributes.codegen.target_feature.allowed-positions]
The `#[target_feature]` attribute is not allowed on the following places:

- [the `main` function][crate.main]
- a [`panic_handler` function][panic.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
be used with a `target_feature` attribute.
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.

r[attributes.codegen.target_feature.availability]
### Available features
Expand All @@ -181,9 +201,7 @@ The following is a list of the available feature names.
r[attributes.codegen.target_feature.x86]
#### `x86` or `x86_64`

Executing code with unsupported features is undefined behavior on this platform.
Hence on this platform usage of `#[target_feature]` functions follows the
[above restrictions][attributes.codegen.target_feature.safety-restrictions].
Executing code with unsupported features is undefined behavior on this platform. 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 @@ -303,11 +321,9 @@ Feature | Implicitly Enables | Description
r[attributes.codegen.target_feature.aarch64]
#### `aarch64`

On this platform the usage of `#[target_feature]` functions follows the
[above restrictions][attributes.codegen.target_feature.safety-restrictions].
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].
Further documentation on these features can be found in the [ARM Architecture Reference Manual], or elsewhere on [developer.arm.com].

[ARM Architecture Reference Manual]: https://developer.arm.com/documentation/ddi0487/latest
[developer.arm.com]: https://developer.arm.com
Expand Down Expand Up @@ -366,8 +382,7 @@ Feature | Implicitly Enables | Feature Name
r[attributes.codegen.target_feature.loongarch]
#### `loongarch`

On this platform the usage of `#[target_feature]` functions follows the
[above restrictions][attributes.codegen.target_feature.safety-restrictions].
On this platform the usage of `#[target_feature]` functions follows the [above restrictions][attributes.codegen.target_feature.safety-restrictions].

Feature | Implicitly Enables | Description
------------|---------------------|-------------------
Expand All @@ -392,12 +407,9 @@ Feature | Implicitly Enables | Description
r[attributes.codegen.target_feature.riscv]
#### `riscv32` or `riscv64`

On this platform the usage of `#[target_feature]` functions follows the
[above restrictions][attributes.codegen.target_feature.safety-restrictions].
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
in another manual hosted on the [RISC-V GitHub Account].
Further documentation on these features can be found in their respective specification. Many specifications are described in the [RISC-V ISA Manual] or in another manual hosted on the [RISC-V GitHub Account].

[RISC-V ISA Manual]: https://github.com/riscv/riscv-isa-manual
[RISC-V GitHub Account]: https://github.com/riscv
Expand Down Expand Up @@ -453,11 +465,7 @@ Feature | Implicitly Enables | Description
r[attributes.codegen.target_feature.wasm]
#### `wasm32` or `wasm64`

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.
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 All @@ -483,22 +491,6 @@ Feature | Implicitly Enables | Description
[tail-call]: https://github.com/webassembly/tail-call
[multivalue]: https://github.com/webassembly/multi-value

r[attributes.codegen.target_feature.info]
### Additional information

r[attributes.codegen.target_feature.remark-cfg]
See the [`target_feature` conditional compilation option] for selectively
enabling or disabling compilation of code based on compile-time settings. Note
that this option is not affected by the `target_feature` attribute, and is
only driven by the features enabled for the entire crate.

r[attributes.codegen.target_feature.remark-rt]
See the [`is_x86_feature_detected`] or [`is_aarch64_feature_detected`] macros
in the standard library for runtime feature detection on these platforms.

> [!NOTE]
> `rustc` has a default set of features enabled for each target and CPU. The CPU may be chosen with the [`-C target-cpu`] flag. Individual features may be enabled or disabled for an entire crate with the [`-C target-feature`] flag.

r[attributes.codegen.track_caller]
## The `track_caller` attribute

Expand Down