From ecf55f83fe411df743b710f066592249e65b5770 Mon Sep 17 00:00:00 2001 From: Jonathan Pallant Date: Thu, 10 Sep 2026 11:21:32 +0100 Subject: [PATCH] Improve Armv7-R documentation People have fallen over the issue where `target-cpu=cortex-r5` unexpectedly turns on FPU support, even on an EABI soft-float target. So this update attempts to document the full set of Armv7-R processors, their FPU options, and how to set things up for the precise combination you have. It is modelled after the Armv7E-M documentation. --- .../src/platform-support/armv7r-none-eabi.md | 83 ++++++++++++++++--- 1 file changed, 70 insertions(+), 13 deletions(-) diff --git a/src/doc/rustc/src/platform-support/armv7r-none-eabi.md b/src/doc/rustc/src/platform-support/armv7r-none-eabi.md index c40ceda7bfca0..c08841489b78b 100644 --- a/src/doc/rustc/src/platform-support/armv7r-none-eabi.md +++ b/src/doc/rustc/src/platform-support/armv7r-none-eabi.md @@ -3,18 +3,30 @@ * **Tier: 2** * **Library Support:** core and alloc (bare-metal, `#![no_std]`) -Bare-metal target for CPUs in the Armv7-R architecture family, supporting dual -ARM/Thumb mode. The `armv7r-none-eabi*` targets use Arm mode by default and the -`thumbv7r-none-eabi*` targets use Thumb mode by default. The `-eabi` targets use -a soft-float ABI and do not require an FPU, while the `-eabihf` targets use a -hard-float ABI and do require an FPU. +Bare-metal target for CPUs in the [Armv7-R] architecture family, supporting both +the [A32 (Arm) ISA][a32-isa] and [T32 (Thumb) ISA][t32-isa]. -Processors in this family include the [Arm Cortex-R4, 5, 7, and 8][cortex-r]. +The `armv7r-none-eabi*` targets use A32 (Arm) mode by default and the +`thumbv7r-none-eabi*` targets use T32 (Thumb) mode by default. + +Processors in this family include the: + +* [Arm Cortex-R4][cortex-r4] +* [Arm Cortex-R5][cortex-r5] +* [Arm Cortex-R7][cortex-r7] +* [Arm Cortex-R8][cortex-r8] See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all -`arm-none-eabi` targets. +`arm-none-eabi` targets, in particular the difference between the `eabi` and +`eabihf` ABI. -[cortex-r]: https://en.wikipedia.org/wiki/ARM_Cortex-R +[t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture +[a32-isa]: https://developer.arm.com/Architectures/A32%20Instruction%20Set%20Architecture +[Armv7-R]: https://support.arm.com/documentation/ddi0406 +[cortex-r4]: https://developer.arm.com/Processors/Cortex-R4 +[cortex-r5]: https://developer.arm.com/Processors/Cortex-R5 +[cortex-r7]: https://developer.arm.com/Processors/Cortex-R7 +[cortex-r8]: https://developer.arm.com/Processors/Cortex-R8 ## Target maintainers @@ -31,18 +43,63 @@ See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all When using the hardfloat (`-eabibf`) targets, the minimum floating-point features assumed are those of the `vfpv3-d16`, which includes single- and -double-precision, with 16 double-precision registers. This floating-point unit -appears in Cortex-R4F and Cortex-R5F processors. See [VFP in the Cortex-R +double-precision, with 16 double-precision registers. See [VFP in the Cortex-R processors][vfp] for more details on the possible FPU variants. If your processor supports a different set of floating-point features than the -default expectations of `vfpv3-d16`, then these should also be enabled or -disabled as needed with `-C target-feature=(+/-)`. +default expectations of `vfpv3-d16` (for example, if it only supports +single-precision and not double-precision), then those features should also be +enabled or disabled as needed with `-C target-feature=(+/-)` (or using a custom +JSON target). If you are removing features then you will also need to recompile +the Rust Standard Library from source (e.g. using `-Zbuild-std=core`). -[endianness]: https://developer.arm.com/documentation/den0042/a/Coding-for-Cortex-R-Processors/Endianness +See [the bare-metal Arm +docs](arm-none-eabi.md#target-cpu-and-target-feature-options) for details on how +to use these flags. [vfp]: https://developer.arm.com/documentation/den0042/a/Floating-Point/Floating-point-basics-and-the-IEEE-754-standard/VFP-in-the-Cortex-R-processors + +### Table of supported CPUs for `(arm|thumb)v7r-none-eabi` + +| CPU | FPU | Target CPU | Target Features | +|-----------|-----|-------------|-----------------| +| Any | No | None | None | +| Cortex-R4 | No | `cortex-r4` | None | +| Cortex-R4 | DP | `cortex-r4` | `+vfp3` | +| Cortex-R4 | SP | `cortex-r4` | `+vfp3,-fp64` | +| Cortex-R5 | No | `cortex-r5` | `-fpregs` | +| Cortex-R5 | DP | `cortex-r5` | None | +| Cortex-R5 | SP | `cortex-r5` | `-fp64` | +| Cortex-R7 | No | `cortex-r7` | `-fpregs` | +| Cortex-R7 | DP | `cortex-r7` | None | +| Cortex-R7 | SP | `cortex-r7` | `-fp64` | +| Cortex-R8 | No | `cortex-r8` | `-fpregs` | +| Cortex-R8 | DP | `cortex-r8` | None | +| Cortex-R8 | SP | `cortex-r8` | `-fp64` | + +### Table of supported CPUs for `(arm|thumb)v7r-none-eabihf` + +| CPU | FPU | Target CPU | Target Features | +|-----------|-----|-------------|-----------------| +| Any | DP | None | None | +| Any | SP | None | `-fp64` | +| Cortex-R4 | DP | `cortex-r4` | None | +| Cortex-R4 | SP | `cortex-r4` | `-fp64` | +| Cortex-R5 | DP | `cortex-r5` | None | +| Cortex-R5 | SP | `cortex-r5` | `-fp64` | +| Cortex-R7 | DP | `cortex-r7` | None | +| Cortex-R7 | SP | `cortex-r7` | `-fp64` | +| Cortex-R8 | DP | `cortex-r8` | None | +| Cortex-R8 | SP | `cortex-r8` | `-fp64` | + +
+ +Never use the `-fpregs` *target-feature* with the `(arm|thumb)v7r-none-eabi` targets +as it will cause compilation units to have different ABIs, which is unsound. + +
+ ## Start-up and Low-Level Code The [Rust Embedded Devices Working Group Arm Team] maintain the [`aarch32-cpu`]