From a9022d4680cfa60d56aa240f093c65b7dd99481f Mon Sep 17 00:00:00 2001 From: Jonathan Pallant Date: Mon, 29 Apr 2024 10:13:42 +0100 Subject: [PATCH] Arm target doc wording tweaks based on review comments. --- .../src/platform-support/arm-none-eabi.md | 50 +++++++++++-------- .../platform-support/thumbv6m-none-eabi.md | 2 +- .../platform-support/thumbv7em-none-eabi.md | 6 +-- .../platform-support/thumbv7m-none-eabi.md | 2 +- .../thumbv8m.base-none-eabi.md | 2 +- .../thumbv8m.main-none-eabi.md | 2 +- 6 files changed, 37 insertions(+), 27 deletions(-) diff --git a/src/doc/rustc/src/platform-support/arm-none-eabi.md b/src/doc/rustc/src/platform-support/arm-none-eabi.md index 4bd1d68fb755e..55d2f50b76213 100644 --- a/src/doc/rustc/src/platform-support/arm-none-eabi.md +++ b/src/doc/rustc/src/platform-support/arm-none-eabi.md @@ -30,24 +30,34 @@ ## Common Target Details -This documentation covers details that apply to a range of bare-metal target for -32-bit ARM CPUs. In addition, target specific details may be covered in their -own document. +This documentation covers details that apply to a range of bare-metal targets +for 32-bit ARM CPUs. In addition, target specific details may be covered in +their own document. If a target ends in `eabi`, that target uses the so-called *soft-float ABI*: functions which take `f32` or `f64` as arguments will have those values packed into integer registers. This means that an FPU is not required from an ABI -perspective, but within a function FPU instructions may still be used if the -code is compiled with a `target-cpu` or `target-feature` option that enables -FPU support. +perspective, but within a function floating-point instructions may still be used +if the code is compiled with a `target-cpu` or `target-feature` option that +enables FPU support. -If a target ends if `eabihf`, that target uses the so-called *hard-float ABI*: +If a target ends in `eabihf`, that target uses the so-called *hard-float ABI*: functions which take `f32` or `f64` as arguments will have them passed via FPU -registers. These targets therefore require the use of an FPU and will assume the -minimum support FPU for that architecture is available. More advanced FPU -instructions (e.g. ones that work on double-precision `f64` values) may be +registers. These targets therefore require the availability of an FPU and will +assume some baseline level of floating-point support is available (which can +vary depending on the target). More advanced floating-point instructions may be generated if the code is compiled with a `target-cpu` or `target-feature` option -that enables such additional FPU support. +that enables such additional FPU support. For example, if a given hard-float +target has baseline *single-precision* (`f32`) support in hardware, there may be +`target-cpu` or `target-feature` options that tell LLVM to assume your processor +in fact also has *double-precision* (`f64`) support. + +You may of course use the `f32` and `f64` types in your code, regardless of the +ABI being used, or the level of support your processor has for performing such +operations in hardware. Any floating-point operations that LLVM assumes your +processor cannot support will be lowered to library calls (like `__aeabi_dadd`) +which perform the floating-point operation in software using integer +instructions. ## Target CPU and Target Feature options @@ -61,7 +71,7 @@ It is important to note that selecting a *target-cpu* will typically enable *all* the optional features available from Arm on that model of CPU and your particular implementation of that CPU may not have those features available. In that case, you can use `-C target-feature=-option` to turn off the specific CPU -features you do not have available, leaving you with the optimised instruction +features you do not have available, leaving you with the optimized instruction scheduling and support for the features you do have. More details are available in the detailed target-specific documentation. @@ -76,13 +86,13 @@ uses (likely linker related ones): ```toml rustflags = [ # Usual Arm bare-metal linker setup - "-C", "link-arg=-Tlink.x", - "-C", "link-arg=--nmagic", + "-Clink-arg=-Tlink.x", + "-Clink-arg=--nmagic", # tell Rust we have a Cortex-M55 - "-C", "target-cpu=cortex-m55", + "-Ctarget-cpu=cortex-m55", # tell Rust our Cortex-M55 doesn't have Floating-Point M-Profile Vector # Extensions (but it does have everything else a Cortex-M55 could have). - "-C", "target-feature=-mve.fp" + "-Ctarget-feature=-mve.fp" ] [build] @@ -157,10 +167,10 @@ Most of `core` should work as expected, with the following notes: Rust programs are output as ELF files. -[atomic-load]: https://doc.rust-lang.org/stable/std/sync/atomic/struct.AtomicU32.html#method.load -[atomic-store]: https://doc.rust-lang.org/stable/std/sync/atomic/struct.AtomicU32.html#method.store -[fetch-add]: https://doc.rust-lang.org/stable/std/sync/atomic/struct.AtomicU32.html#method.fetch_add -[compare-exchange]: https://doc.rust-lang.org/stable/std/sync/atomic/struct.AtomicU32.html#method.compare_exchange +[atomic-load]: https://doc.rust-lang.org/stable/core/sync/atomic/struct.AtomicU32.html#method.load +[atomic-store]: https://doc.rust-lang.org/stable/core/sync/atomic/struct.AtomicU32.html#method.store +[fetch-add]: https://doc.rust-lang.org/stable/core/sync/atomic/struct.AtomicU32.html#method.fetch_add +[compare-exchange]: https://doc.rust-lang.org/stable/core/sync/atomic/struct.AtomicU32.html#method.compare_exchange ## Testing diff --git a/src/doc/rustc/src/platform-support/thumbv6m-none-eabi.md b/src/doc/rustc/src/platform-support/thumbv6m-none-eabi.md index f75194c815e0a..32f2a573973fb 100644 --- a/src/doc/rustc/src/platform-support/thumbv6m-none-eabi.md +++ b/src/doc/rustc/src/platform-support/thumbv6m-none-eabi.md @@ -15,7 +15,7 @@ See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all `arm-none-eabi` targets. This target uses the soft-float ABI: functions which take `f32` or `f64` as -arguments will have those values packed into an integer registers. This is the +arguments will have those values packed into integer registers. This is the only option because there is no FPU support in [ARMv6-M]. [t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture diff --git a/src/doc/rustc/src/platform-support/thumbv7em-none-eabi.md b/src/doc/rustc/src/platform-support/thumbv7em-none-eabi.md index 632f1681bb9c9..78a431fec9339 100644 --- a/src/doc/rustc/src/platform-support/thumbv7em-none-eabi.md +++ b/src/doc/rustc/src/platform-support/thumbv7em-none-eabi.md @@ -14,7 +14,7 @@ See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all `arm-none-eabi` targets. This target uses the soft-float ABI: functions which take `f32` or `f64` as -arguments will have those values packed into an integer registers. This target +arguments will have those values packed into integer registers. This target therefore does not require the use of an FPU (which is optional on Cortex-M4 and Cortex-M7), but an FPU can be optionally enabled if desired. See also the hard-float ABI version of this target @@ -52,7 +52,7 @@ The target CPU is `cortex-m4`. * All Cortex-M4 have DSP extensions * support is controlled by the `dsp` *target-feature* - * enabled by default with this *target-cpu* + * enabled by default with this *target* * Cortex-M4F has a single precision FPU * support is enabled by default with this *target-cpu* * disable support using the `+soft-float` feature @@ -63,7 +63,7 @@ The target CPU is `cortex-m7`. * All Cortex-M7 have DSP extensions * support is controlled by the `dsp` *target-feature* - * enabled by default with this *target-cpu* + * enabled by default with this *target* * Cortex-M7F have either a single-precision or double-precision FPU * double-precision support is enabled by default with this *target-cpu* * opt-out by using the `-f64` *target-feature* diff --git a/src/doc/rustc/src/platform-support/thumbv7m-none-eabi.md b/src/doc/rustc/src/platform-support/thumbv7m-none-eabi.md index 2c10f679f6655..793e0d7d2de90 100644 --- a/src/doc/rustc/src/platform-support/thumbv7m-none-eabi.md +++ b/src/doc/rustc/src/platform-support/thumbv7m-none-eabi.md @@ -13,7 +13,7 @@ See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all `arm-none-eabi` targets. This target uses the soft-float ABI: functions which take `f32` or `f64` as -arguments will have those values packed into an integer registers. This is the +arguments will have those values packed into integer registers. This is the only option because there is no FPU support in [ARMv7-M]. [t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture diff --git a/src/doc/rustc/src/platform-support/thumbv8m.base-none-eabi.md b/src/doc/rustc/src/platform-support/thumbv8m.base-none-eabi.md index 6e9d2329aa924..9733ce0e0aac9 100644 --- a/src/doc/rustc/src/platform-support/thumbv8m.base-none-eabi.md +++ b/src/doc/rustc/src/platform-support/thumbv8m.base-none-eabi.md @@ -13,7 +13,7 @@ See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all `arm-none-eabi` targets. This target uses the soft-float ABI: functions which take `f32` or `f64` as -arguments will have those values packed into an integer registers. This is the +arguments will have those values packed into integer registers. This is the only option because there is no FPU support in [ARMv6-M]. [t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture diff --git a/src/doc/rustc/src/platform-support/thumbv8m.main-none-eabi.md b/src/doc/rustc/src/platform-support/thumbv8m.main-none-eabi.md index eca9a7b1a701b..cbac897390e86 100644 --- a/src/doc/rustc/src/platform-support/thumbv8m.main-none-eabi.md +++ b/src/doc/rustc/src/platform-support/thumbv8m.main-none-eabi.md @@ -16,7 +16,7 @@ See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all `arm-none-eabi` targets. This target uses the soft-float ABI: functions which take `f32` or `f64` as -arguments will have those values packed into an integer registers. This target +arguments will have those values packed into integer registers. This target therefore does not require the use of an FPU (which is optional on Cortex-M33, Cortex-M55 and Cortex-M85), but an FPU can be optionally enabled if desired. See also the hard-float ABI version of this target