From 5ffe3108f2b0be6fa92bc0e18f996b79cad0bd25 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sat, 21 Jun 2025 18:11:38 -0700 Subject: [PATCH 1/2] Update instruction_set to use the attribute template --- src/attributes/codegen.md | 45 +++++++++++++++++++++++++-------------- 1 file changed, 29 insertions(+), 16 deletions(-) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 24e4c2c3a..20ffacfc2 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -637,34 +637,47 @@ trait object whose methods are attributed. r[attributes.codegen.instruction_set] ## The `instruction_set` attribute -r[attributes.codegen.instruction_set.allowed-positions] -The *`instruction_set` [attribute]* may be applied to a function to control which instruction set the function will be generated for. +r[attributes.codegen.instruction_set.intro] +The *`instruction_set` [attribute]* specifies the instruction set that a function will use during code generation. This allows mixing more than one instruction set in a single program. -r[attributes.codegen.instruction_set.behavior] -This allows mixing more than one instruction set in a single program on CPU architectures that support it. +> [!EXAMPLE] +> +> ```rust,ignore +> #[instruction_set(arm::a32)] +> fn foo_arm_code() {} +> +> #[instruction_set(arm::t32)] +> fn bar_thumb_code() {} +> ``` r[attributes.codegen.instruction_set.syntax] -It uses the [MetaListPaths] syntax, and a path comprised of the architecture family name and instruction set name. +The `instruction_set` attribute uses the [MetaListPaths] syntax, and a path comprised of the architecture family name and instruction set name. + +r[attributes.codegen.instruction_set.allowed-positions] +The `instruction_set` attribute 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 +- [Closures][expr.closure] + +> [!NOTE] +> `rustc` currently ignores `instruction_set` in other positions. This may change in the future. + +r[attributes.codegen.instruction_set.duplicates] +The `instruction_set` attribute may only be specified once on an item. r[attributes.codegen.instruction_set.target-limits] -It is a compilation error to use the `instruction_set` attribute on a target that does not support it. +The `instruction_set` attribute may only be used with a target that supports the given value. r[attributes.codegen.instruction_set.arm] -### On ARM +### `instruction_set` on ARM For the `ARMv4T` and `ARMv5te` architectures, the following are supported: * `arm::a32` --- Generate the function as A32 "ARM" code. * `arm::t32` --- Generate the function as T32 "Thumb" code. - -```rust,ignore -#[instruction_set(arm::a32)] -fn foo_arm_code() {} - -#[instruction_set(arm::t32)] -fn bar_thumb_code() {} -``` - Using the `instruction_set` attribute has the following effects: * If the address of the function is taken as a function pointer, the low bit of the address will be set to 0 (arm) or 1 (thumb) depending on the instruction set. From 71d7c2aea79a48782045af34d54e7d14d65c9262 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Thu, 21 Aug 2025 20:09:32 +0000 Subject: [PATCH 2/2] Revise `instruction_set` text --- src/attributes/codegen.md | 35 +++++++++++++++++------------------ 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 20ffacfc2..b38b57831 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -634,6 +634,7 @@ trait object whose methods are attributed. > [!NOTE] > The aforementioned shim for function pointers is necessary because `rustc` implements `track_caller` in a codegen context by appending an implicit parameter to the function ABI, but this would be unsound for an indirect call because the parameter is not a part of the function's type and a given function pointer type may or may not refer to a function with the attribute. The creation of a shim hides the implicit parameter from callers of the function pointer, preserving soundness. + r[attributes.codegen.instruction_set] ## The `instruction_set` attribute @@ -644,44 +645,42 @@ The *`instruction_set` [attribute]* specifies the instruction set that a functio > > ```rust,ignore > #[instruction_set(arm::a32)] -> fn foo_arm_code() {} +> fn arm_code() {} > > #[instruction_set(arm::t32)] -> fn bar_thumb_code() {} +> fn thumb_code() {} > ``` r[attributes.codegen.instruction_set.syntax] -The `instruction_set` attribute uses the [MetaListPaths] syntax, and a path comprised of the architecture family name and instruction set name. +The `instruction_set` attribute uses the [MetaListPaths] syntax to specify a single path consisting of the architecture family name and instruction set name. r[attributes.codegen.instruction_set.allowed-positions] -The `instruction_set` attribute 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 -- [Closures][expr.closure] +The `instruction_set` attribute may only be applied to functions, including [closures][expr.closure], [free functions][items.fn], and associated functions defined (i.e. with a body) in [inherent impls][items.associated.fn], [trait impls][items.impl.trait], and [trait definitions][items.traits]. > [!NOTE] -> `rustc` currently ignores `instruction_set` in other positions. This may change in the future. +> `rustc` ignores use in other positions but lints against it. This may become an error in the future. r[attributes.codegen.instruction_set.duplicates] -The `instruction_set` attribute may only be specified once on an item. +The `instruction_set` attribute may be used only once on a function. r[attributes.codegen.instruction_set.target-limits] The `instruction_set` attribute may only be used with a target that supports the given value. +r[attributes.codegen.instruction_set.inline-asm] +When the `instruction_set` attribute is used, any inline assembly in the function must use the specified instruction set instead of the target default. + r[attributes.codegen.instruction_set.arm] ### `instruction_set` on ARM -For the `ARMv4T` and `ARMv5te` architectures, the following are supported: -* `arm::a32` --- Generate the function as A32 "ARM" code. -* `arm::t32` --- Generate the function as T32 "Thumb" code. +When targeting the `ARMv4T` and `ARMv5te` architectures, the supported values for `instruction_set` are: + +- `arm::a32` --- Generate the function as A32 "ARM" code. +- `arm::t32` --- Generate the function as T32 "Thumb" code. -Using the `instruction_set` attribute has the following effects: +If the address of the function is taken as a function pointer, the low bit of the address will depend on the selected instruction set: -* If the address of the function is taken as a function pointer, the low bit of the address will be set to 0 (arm) or 1 (thumb) depending on the instruction set. -* Any inline assembly in the function must use the specified instruction set instead of the target default. +- For `arm::a32` ("ARM"), it will be 0. +- For `arm::t32` ("Thumb"), it will be 1. [`-C target-cpu`]: ../../rustc/codegen-options/index.html#target-cpu [`-C target-feature`]: ../../rustc/codegen-options/index.html#target-feature