diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 7eb98daf07..c61b0c43a2 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -181,42 +181,73 @@ Only the first use of the `no_builtins` attribute has effect. > [!NOTE] > `rustc` lints against any use following the first. + 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. +> +> Whether a feature is enabled can be checked at runtime using a platform-specific macro from the standard library, for instance [`is_x86_feature_detected`] or [`is_aarch64_feature_detected`]. + +> [!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` ignores use in other positions but lints against it. 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`. @@ -252,18 +283,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 @@ -273,9 +294,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 ------------|--------------------|------------------- @@ -399,11 +418,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 @@ -462,8 +479,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 ------------|---------------------|------------------- @@ -488,12 +504,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], -[version 20250508], 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], [version 20250508], or in another manual hosted on the [RISC-V GitHub Account]. [RISC-V ISA Manual]: https://github.com/riscv/riscv-isa-manual [version 20250508]: https://github.com/riscv/riscv-isa-manual/tree/20250508 @@ -548,11 +561,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 ----------------------|---------------------|------------------- @@ -602,21 +611,6 @@ Feature | Implicitly Enables | [z/Architecture Principles of Operation]: https://publibfp.dhe.ibm.com/epubs/pdf/a227832d.pdf -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] -Whether a feature is enabled can be checked at runtime using a platform-specific macro from the standard library, for instance [`is_x86_feature_detected`] or [`is_aarch64_feature_detected`]. - -> [!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