From b0f75628d21ac5409ad0e883f95df0badf13b71d Mon Sep 17 00:00:00 2001 From: Jonathan Pallant Date: Fri, 26 Apr 2024 15:15:35 +0100 Subject: [PATCH 1/8] Add pages for every Cortex-M target Now explains how to, for example, support a Cortex-M55 with FPU and Integer Helium. --- src/doc/rustc/src/platform-support.md | 14 +- .../src/platform-support/arm-none-eabi.md | 147 ++++++++++++++---- .../platform-support/thumbv6m-none-eabi.md | 62 ++++++++ .../platform-support/thumbv7em-none-eabi.md | 70 +++++++++ .../platform-support/thumbv7em-none-eabihf.md | 67 ++++++++ .../platform-support/thumbv7m-none-eabi.md | 44 ++++++ .../thumbv8m.base-none-eabi.md | 44 ++++++ .../thumbv8m.main-none-eabi.md | 124 +++++++++++++++ .../thumbv8m.main-none-eabihf.md | 113 ++++++++++++++ 9 files changed, 646 insertions(+), 39 deletions(-) create mode 100644 src/doc/rustc/src/platform-support/thumbv6m-none-eabi.md create mode 100644 src/doc/rustc/src/platform-support/thumbv7em-none-eabi.md create mode 100644 src/doc/rustc/src/platform-support/thumbv7em-none-eabihf.md create mode 100644 src/doc/rustc/src/platform-support/thumbv7m-none-eabi.md create mode 100644 src/doc/rustc/src/platform-support/thumbv8m.base-none-eabi.md create mode 100644 src/doc/rustc/src/platform-support/thumbv8m.main-none-eabi.md create mode 100644 src/doc/rustc/src/platform-support/thumbv8m.main-none-eabihf.md diff --git a/src/doc/rustc/src/platform-support.md b/src/doc/rustc/src/platform-support.md index 2578b71a158be..526b5a5978995 100644 --- a/src/doc/rustc/src/platform-support.md +++ b/src/doc/rustc/src/platform-support.md @@ -178,15 +178,15 @@ target | std | notes `riscv64imac-unknown-none-elf` | * | Bare RISC-V (RV64IMAC ISA) `sparc64-unknown-linux-gnu` | ✓ | SPARC Linux (kernel 4.4, glibc 2.23) `sparcv9-sun-solaris` | ✓ | SPARC Solaris 11, illumos -[`thumbv6m-none-eabi`](platform-support/arm-none-eabi.md) | * | Bare ARMv6-M -[`thumbv7em-none-eabi`](platform-support/arm-none-eabi.md) | * | Bare ARMv7E-M -[`thumbv7em-none-eabihf`](platform-support/arm-none-eabi.md) | * | Bare ARMV7E-M, hardfloat -[`thumbv7m-none-eabi`](platform-support/arm-none-eabi.md) | * | Bare ARMv7-M +[`thumbv6m-none-eabi`](platform-support/thumbv6m-none-eabi.md) | * | Bare ARMv6-M +[`thumbv7em-none-eabi`](platform-support/thumbv7em-none-eabi.md) | * | Bare ARMv7E-M +[`thumbv7em-none-eabihf`](platform-support/thumbv7em-none-eabihf.md) | * | Bare ARMV7E-M, hardfloat +[`thumbv7m-none-eabi`](platform-support/thumbv7m-none-eabi.md) | * | Bare ARMv7-M [`thumbv7neon-linux-androideabi`](platform-support/android.md) | ✓ | Thumb2-mode ARMv7-A Android with NEON `thumbv7neon-unknown-linux-gnueabihf` | ✓ | Thumb2-mode ARMv7-A Linux with NEON (kernel 4.4, glibc 2.23) -[`thumbv8m.base-none-eabi`](platform-support/arm-none-eabi.md) | * | Bare ARMv8-M Baseline -[`thumbv8m.main-none-eabi`](platform-support/arm-none-eabi.md) | * | Bare ARMv8-M Mainline -[`thumbv8m.main-none-eabihf`](platform-support/arm-none-eabi.md) | * | Bare ARMv8-M Mainline, hardfloat +[`thumbv8m.base-none-eabi`](platform-support/thumbv8m.base-none-eabi.md) | * | Bare ARMv8-M Baseline +[`thumbv8m.main-none-eabi`](platform-support/thumbv8m.main-none-eabi.md) | * | Bare ARMv8-M Mainline +[`thumbv8m.main-none-eabihf`](platform-support/thumbv8m.main-none-eabihf.md) | * | Bare ARMv8-M Mainline, hardfloat `wasm32-unknown-emscripten` | ✓ | WebAssembly via Emscripten `wasm32-unknown-unknown` | ✓ | WebAssembly `wasm32-wasi` | ✓ | WebAssembly with WASI (undergoing a [rename to `wasm32-wasip1`][wasi-rename]) 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 6335a6405a102..de41c5e676a8d 100644 --- a/src/doc/rustc/src/platform-support/arm-none-eabi.md +++ b/src/doc/rustc/src/platform-support/arm-none-eabi.md @@ -1,25 +1,96 @@ # `{arm,thumb}*-none-eabi(hf)?` -**Tier: 2** -- [arm(eb)?v7r-none-eabi(hf)?](armv7r-none-eabi.md) -- armv7a-none-eabi -- thumbv6m-none-eabi -- thumbv7m-none-eabi -- thumbv7em-none-eabi(hf)? -- thumbv8m.base-none-eabi -- thumbv8m.main-none-eabi(hf)? - -**Tier: 3** -- [{arm,thumb}v4t-none-eabi](armv4t-none-eabi.md) -- [{arm,thumb}v5te-none-eabi](armv5te-none-eabi.md) -- armv7a-none-eabihf -- [armv8r-none-eabihf](armv8r-none-eabihf.md) - -Bare-metal target for 32-bit ARM CPUs. - -If a target has a `*hf` variant, that variant uses the hardware floating-point -ABI and enables some minimum set of floating-point features based on the FPU(s) -available in that processor family. +## Tier 2 Target List + +- Arm A-Profile Architectures + - `armv7a-none-eabi` +- Arm R-Profile Architectures + - [`armv7r-none-eabi` and `armv7r-none-eabihf`](armv7r-none-eabi.md) + - [`armebv7r-none-eabi` and `armebv7r-none-eabihf`](armv7r-none-eabi.md) +- Arm M-Profile Architectures + - [`thumbv6m-none-eabi`](thumbv6m-none-eabi.md) + - [`thumbv7m-none-eabi`](thumbv7m-none-eabi.md) + - [`thumbv7em-none-eabi`](thumbv7em-none-eabi.md) and [`thumbv7em-none-eabihf`](thumbv7em-none-eabihf.md) + - [`thumbv8m.base-none-eabi`](thumbv8m.base-none-eabi.md) + - [`thumbv8m.main-none-eabi`](thumbv8m.main-none-eabi.md) and [`thumbv8m.main-none-eabihf`](thumbv8m.main-none-eabihf.md) +- *Legacy* Arm Architectures + - None + +## Tier 3 Target List + +- Arm A-Profile Architectures + - `armv7a-none-eabihf` +- Arm R-Profile Architectures + - [`armv8r-none-eabihf`](armv8r-none-eabihf.md) +- Arm M-Profile Architectures + - None +- *Legacy* Arm Architectures + - [`armv4t-none-eabi` and `thumbv4t-none-eabi`](armv4t-none-eabi.md) + - [`armv5te-none-eabi` and `thumbv5te-none-eabi`](armv5te-none-eabi.md) + +## 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. + +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. + +If a target ends if `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 target 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 +generated if the code is compiled with a `target-cpu` or `target-feature` option +that enables such additional FPU support. + +## Target CPU and Target Feature options + +It is possible to tell Rust (or LLVM) that you have a specific model of Arm +processor, using the [`-C target-cpu`][target-cpu] option. You can also control +whether Rust (or LLVM) will include instructions that target optional hardware +features, e.g. hardware floating point, or vector maths operations, using [`-C +target-feature`][target-feature]. + +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 +scheduling and support for the features you do have. More details are available +in the detailed target-specific documentation. + +**Note:** Many target-features are currently unstable and subject to change, and +if you use them you should dissassmble the compiler output and manually inspect +it to ensure only appropriate instructions for your CPU have been generated. + +If do you wish to use the *target-cpu* and *target-feature* options, you can add +them to your `.cargo/config.toml` file alongside any other flags your project +uses (likely linker related ones): + +```toml +rustflags = [ + # Usual Arm bare-metal linker setup + "-C", "link-arg=-Tlink.x", + "-C", "link-arg=--nmagic", + # tell Rust we have a Cortex-M55 + "-C", "target-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" +] + +[build] +target = "thumbv8m.main-none-eabihf" +``` + +[target-cpu]: https://doc.rust-lang.org/rustc/codegen-options/index.html#target-cpu +[target-feature]: https://doc.rust-lang.org/rustc/codegen-options/index.html#target-feature ## Requirements @@ -45,14 +116,15 @@ according to the specific device you are using. Pass `-Clink-arg=-Tyour_script.ld` as a rustc argument to make the linker use `your_script.ld` during linking. -Targets named `thumb*` instead of `arm*` -generate Thumb-mode code by default. M-profile processors (`thumbv*m*-*` -targets) only support Thumb-mode code. -For the `arm*` targets, Thumb-mode code generation can be enabled by using -`-C target-feature=+thumb-mode`. Using the unstable -`#![feature(arm_target_feature)]`, the attribute -`#[target_feature(enable = "thumb-mode")]` can be applied to individual -`unsafe` functions to cause those functions to be compiled to Thumb-mode code. +Targets named `thumb*` instead of `arm*` generate Thumb (T32) code by default +instead of Arm (A32) code. Most Arm chips support both Thumb mode and Arm mode, +except that M-profile processors (`thumbv*m*-*` targets) only support Thumb-mode. + +For the `arm*` targets, Thumb-mode code generation can be enabled by using `-C +target-feature=+thumb-mode`. Using the unstable +`#![feature(arm_target_feature)]`, the attribute `#[target_feature(enable = +"thumb-mode")]` can be applied to individual `unsafe` functions to cause those +functions to be compiled to Thumb-mode code. ## Building Rust Programs @@ -69,16 +141,27 @@ build-std = ["core"] ``` Most of `core` should work as expected, with the following notes: -* If the target is not `*hf`, then floating-point operations are emulated in - software. + +* Floating-point operations are emulated in software unless LLVM is told to + enable FPU support (either by using an `eabihf` target, specifying a + `target-cpu` with FPU support, or using a `target-feature` to support for a + specific kind of FPU) * Integer division is also emulated in software on some targets, depending on - the CPU. -* Architectures prior to ARMv7 don't have atomic instructions. + the target, `target-cpu` and `target-feature`s. +* Older Arm architectures (e.g. Armv4, Armv5TE and Armv6-M) are limited to basic + [`load`][atomic-load] and [`store`][atomic-store] operations, and not more + advanced operations like [`fetch_add`][fetch-add] or + [`compare_exchange`][compare-exchange]. `alloc` is also supported, as long as you provide your own global allocator. 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 + ## Testing This is a cross-compiled target that you will need to emulate during 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 new file mode 100644 index 0000000000000..f75194c815e0a --- /dev/null +++ b/src/doc/rustc/src/platform-support/thumbv6m-none-eabi.md @@ -0,0 +1,62 @@ +# `thumbv6m-none-eabi` + +**Tier: 2** + +Bare-metal target for CPUs in the [ARMv6-M] architecture family, supporting a +subset of the [T32 ISA][t32-isa]. + +Processors in this family include the: + +* [Arm Cortex-M0][cortex-m0] +* [Arm Cortex-M0+][cortex-m0plus] +* [Arm Cortex-M1][cortex-m1] + +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 +only option because there is no FPU support in [ARMv6-M]. + +[t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture +[ARMv6-M]: https://developer.arm.com/documentation/ddi0419/latest/ +[cortex-m0]: https://developer.arm.com/Processors/Cortex-M0 +[cortex-m0plus]: https://developer.arm.com/Processors/Cortex-M0+ +[cortex-m1]: https://developer.arm.com/Processors/Cortex-M1 + +## Target maintainers + +* [Rust Embedded Devices Working Group Cortex-M + Team](https://github.com/rust-embedded), `cortex-m@teams.rust-embedded.org` + +## Target CPU and Target Feature options + +See [the bare-metal Arm +docs](arm-none-eabi.md#target-cpu-and-target-feature-options) for details on how +to use these flags. + +### Table of supported CPUs + +| CPU | FPU | Target CPU | Target Features | +| ---------- | --- | --------------- | --------------------- | +| Cortex-M0 | No | `cortex-m0` | None | +| Cortex-M0+ | No | `cortex-m0plus` | None | +| Cortex-M1 | No | `cortex-m1` | None | + +### Arm Cortex-M0 + +The target CPU option is `cortex-m0`. + +There are no relevant feature flags, and the FPU is not available. + +### Arm Cortex-M0+ + +The target CPU option is `cortex-m0plus`. + +There are no relevant feature flags, and the FPU is not available. + +### Arm Cortex-M1 + +The target CPU option is `cortex-m1`. + +There are no relevant feature flags, and the FPU is not available. diff --git a/src/doc/rustc/src/platform-support/thumbv7em-none-eabi.md b/src/doc/rustc/src/platform-support/thumbv7em-none-eabi.md new file mode 100644 index 0000000000000..632f1681bb9c9 --- /dev/null +++ b/src/doc/rustc/src/platform-support/thumbv7em-none-eabi.md @@ -0,0 +1,70 @@ +# `thumbv7em-none-eabi` + +**Tier: 2** + +Bare-metal target for CPUs in the [ARMv7E-M] architecture family, supporting a +subset of the [T32 ISA][t32-isa]. + +Processors in this family include the: + +* [Arm Cortex-M4][cortex-m4] and Arm Cortex-M4F +* [Arm Cortex-M7][cortex-m7] and Arm Cortex-M7F + +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 +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 +[`thumbv7em-none-eabihf`](thumbv7em-none-eabihf.md). + +[t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture +[ARMv7E-M]: https://developer.arm.com/documentation/ddi0403/latest/ +[cortex-m4]: https://developer.arm.com/Processors/Cortex-M4 +[cortex-m7]: https://developer.arm.com/Processors/Cortex-M7 + +## Target maintainers + +* [Rust Embedded Devices Working Group Cortex-M + Team](https://github.com/rust-embedded), `cortex-m@teams.rust-embedded.org` + +## Target CPU and Target Feature options + +See [the bare-metal Arm +docs](arm-none-eabi.md#target-cpu-and-target-feature-options) for details on how +to use these flags. + +### Table of supported CPUs + +| CPU | FPU | DSP | Target CPU | Target Features | +| ---------- | --- | --- | ----------- | --------------- | +| Cortex-M4 | No | Yes | `cortex-m4` | `+soft-float` | +| Cortex-M4F | SP | Yes | `cortex-m4` | None | +| Cortex-M7 | No | Yes | `cortex-m7` | `+soft-float` | +| Cortex-M7F | SP | Yes | `cortex-m7` | `-fp64` | +| Cortex-M7F | DP | Yes | `cortex-m7` | None | + +### Arm Cortex-M4 and Arm Cortex-M4F + +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* +* Cortex-M4F has a single precision FPU + * support is enabled by default with this *target-cpu* + * disable support using the `+soft-float` feature + +### Arm Cortex-M7 and Arm Cortex-M7F + +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* +* 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* + * disable support entirely using the `+soft-float` feature diff --git a/src/doc/rustc/src/platform-support/thumbv7em-none-eabihf.md b/src/doc/rustc/src/platform-support/thumbv7em-none-eabihf.md new file mode 100644 index 0000000000000..d4c93e3197c79 --- /dev/null +++ b/src/doc/rustc/src/platform-support/thumbv7em-none-eabihf.md @@ -0,0 +1,67 @@ +# `thumbv7em-none-eabihf` + +**Tier: 2** + +Bare-metal target for CPUs in the [ARMv7E-M] architecture family that have an +FPU, supporting a subset of the [T32 ISA][t32-isa]. + +Processors in this family include the: + +* [Arm Cortex-M4F][cortex-m4] +* [Arm Cortex-M7F][cortex-m7] + +See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all +`arm-none-eabi` targets. + +This target uses the hard-float ABI: functions which take `f32` or `f64` as +arguments will have them passed via FPU registers. This target therefore +requires the use of an FPU (which is optional on Cortex-M4 and Cortex-M7). See +also the soft-float ABI version of this target +[`thumbv7em-none-eabi`](thumbv7em-none-eabi.md). + +[t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture +[ARMv7E-M]: https://developer.arm.com/documentation/ddi0403/latest/ +[cortex-m4]: https://developer.arm.com/Processors/Cortex-M4 +[cortex-m7]: https://developer.arm.com/Processors/Cortex-M7 + +## Target maintainers + +* [Rust Embedded Devices Working Group Cortex-M + Team](https://github.com/rust-embedded), `cortex-m@teams.rust-embedded.org` + +## Target CPU and Target Feature options + +See [the bare-metal Arm +docs](arm-none-eabi.md#target-cpu-and-target-feature-options) for details on how +to use these flags. + +### Table of supported CPUs + +| CPU | FPU | DSP | Target CPU | Target Features | +| ---------- | --- | --- | ----------- | --------------- | +| Cortex-M4F | SP | Yes | `cortex-m4` | None | +| Cortex-M7F | SP | Yes | `cortex-m7` | `-fp64` | +| Cortex-M7F | DP | Yes | `cortex-m7` | None | + +### Arm Cortex-M4 and Arm Cortex-M4F + +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* +* Cortex-M4F has a single precision FPU + * support is enabled by default with this *target* + * support is required when using the hard-float ABI + +### Arm Cortex-M7 and Arm Cortex-M7F + +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* +* Cortex-M7F have either a single-precision or double-precision FPU + * single precision support is enabled by default with this *target* + * 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 new file mode 100644 index 0000000000000..2c10f679f6655 --- /dev/null +++ b/src/doc/rustc/src/platform-support/thumbv7m-none-eabi.md @@ -0,0 +1,44 @@ +# `thumbv7m-none-eabi` + +**Tier: 2** + +Bare-metal target for CPUs in the [ARMv7-M] architecture family, supporting a +subset of the [T32 ISA][t32-isa]. + +Processors in this family include the: + +* [Arm Cortex-M3][cortex-m3] + +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 +only option because there is no FPU support in [ARMv7-M]. + +[t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture +[ARMv7-M]: https://developer.arm.com/documentation/ddi0403/latest/ +[cortex-m3]: https://developer.arm.com/Processors/Cortex-M3 + +## Target maintainers + +* [Rust Embedded Devices Working Group Cortex-M + Team](https://github.com/rust-embedded), `cortex-m@teams.rust-embedded.org` + +## Target CPU and Target Feature options + +See [the bare-metal Arm +docs](arm-none-eabi.md#target-cpu-and-target-feature-options) for details on how +to use these flags. + +### Table of supported CPUs + +| CPU | FPU | Target CPU | Target Features | +| ---------- | --- | ----------- | --------------------- | +| Cortex-M3 | No | `cortex-m3` | None | + +### Arm Cortex-M3 + +The target CPU option is `cortex-m3`. + +There are no relevant feature flags, and the FPU is not available. 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 new file mode 100644 index 0000000000000..6e9d2329aa924 --- /dev/null +++ b/src/doc/rustc/src/platform-support/thumbv8m.base-none-eabi.md @@ -0,0 +1,44 @@ +# `thumbv8m.base-none-eabi` + +**Tier: 2** + +Bare-metal target for CPUs in the Baseline [ARMv8-M] architecture family, +supporting a subset of the [T32 ISA][t32-isa]. + +Processors in this family include the: + +* [Arm Cortex-M23][cortex-m23] + +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 +only option because there is no FPU support in [ARMv6-M]. + +[t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture +[ARMv8-M]: https://developer.arm.com/documentation/ddi0553/latest/ +[cortex-m23]: https://developer.arm.com/Processors/Cortex-M23 + +## Target maintainers + +* [Rust Embedded Devices Working Group Cortex-M + Team](https://github.com/rust-embedded), `cortex-m@teams.rust-embedded.org` + +## Target CPU and Target Feature options + +See [the bare-metal Arm +docs](arm-none-eabi.md#target-cpu-and-target-feature-options) for details on how +to use these flags. + +### Table of supported CPUs + +| CPU | FPU | Target CPU | Target Features | +| ----------- | --- | ------------ | --------------------- | +| Cortex-M23 | No | `cortex-m23` | None | + +### Arm Cortex-M23 + +The target CPU option is `cortex-m23`. + +There are no relevant feature flags, and the FPU is not available. 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 new file mode 100644 index 0000000000000..eca9a7b1a701b --- /dev/null +++ b/src/doc/rustc/src/platform-support/thumbv8m.main-none-eabi.md @@ -0,0 +1,124 @@ +# `thumbv8m.main-none-eabi` + +**Tier: 2** + +Bare-metal target for CPUs in the Mainline [ARMv8-M] architecture family, +supporting a subset of the [T32 ISA][t32-isa]. + +Processors in this family include the: + +* [Arm Cortex-M33][cortex-m33] +* [Arm Cortex-M35P][cortex-m35p] +* [Arm Cortex-M55][cortex-m55] +* [Arm Cortex-M85][cortex-m85] + +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 +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 +[`thumbv8m.main-none-eabihf`](thumbv7em-none-eabihf.md). + +[t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture +[ARMv8-M]: https://developer.arm.com/documentation/ddi0553/latest/ +[cortex-m33]: https://developer.arm.com/Processors/Cortex-M33 +[cortex-m35p]: https://developer.arm.com/Processors/Cortex-M35P +[cortex-m55]: https://developer.arm.com/Processors/Cortex-M55 +[cortex-m85]: https://developer.arm.com/Processors/Cortex-M85 + +## Target maintainers + +* [Rust Embedded Devices Working Group Cortex-M + Team](https://github.com/rust-embedded), `cortex-m@teams.rust-embedded.org` + +## Target CPU and Target Feature options + +See [the bare-metal Arm +docs](arm-none-eabi.md#target-cpu-and-target-feature-options) for details on how +to use these flags. + +### Table of supported CPUs + +| CPU | FPU | DSP | MVE | Target CPU | Target Features | +| ----------- | --- | --- | --------- | ------------- | --------------------- | +| Cortex-M33 | No | No | N/A | `cortex-m33` | `+soft-float,-dsp` | +| Cortex-M33 | No | Yes | N/A | `cortex-m33` | `+soft-float` | +| Cortex-M33 | SP | No | N/A | `cortex-m33` | `-dsp` | +| Cortex-M33 | SP | Yes | N/A | `cortex-m33` | None | +| Cortex-M35P | No | No | N/A | `cortex-m35p` | `+soft-float,-dsp` | +| Cortex-M35P | No | Yes | N/A | `cortex-m35p` | `+soft-float` | +| Cortex-M35P | SP | No | N/A | `cortex-m35p` | `-dsp` | +| Cortex-M35P | SP | Yes | N/A | `cortex-m35p` | None | +| Cortex-M55 | No | Yes | No | `cortex-m55` | `+soft-float,-mve` | +| Cortex-M55 | DP | Yes | No | `cortex-m55` | `-mve` | +| Cortex-M55 | No | Yes | Int | `cortex-m55` | `+soft-float,-mve.fp` | +| Cortex-M55 | DP | Yes | Int | `cortex-m55` | `-mve.fp` | +| Cortex-M55 | DP | Yes | Int+Float | `cortex-m55` | None | +| Cortex-M85 | No | Yes | No | `cortex-m85` | `+soft-float,-mve` | +| Cortex-M85 | DP | Yes | No | `cortex-m85` | `-mve` | +| Cortex-M85 | No | Yes | Int | `cortex-m85` | `+soft-float,-mve.fp` | +| Cortex-M85 | DP | Yes | Int | `cortex-m85` | `-mve.fp` | +| Cortex-M85 | DP | Yes | Int+Float | `cortex-m85` | None | + +### Arm Cortex-M33 + +The target CPU is `cortex-m33`. + +* Has optional DSP extensions + * support is controlled by the `dsp` *target-feature* + * enabled by default with this *target-cpu* +* Has an optional single precision FPU + * support is enabled by default with this *target-cpu* + * disable support using the `+soft-float` feature + +### Arm Cortex-M35P + +The target CPU is `cortex-m35p`. + +* Has optional DSP extensions + * support is controlled by the `dsp` *target-feature* + * enabled by default with this *target-cpu* +* Has a single precision FPU + * support is enabled by default with this *target-cpu* + * disable support using the `+soft-float` feature + +### Arm Cortex-M55 + +The target CPU is `cortex-m55`. + +* Has DSP extensions + * support is controlled by the `dsp` *target-feature* + * enabled by default with this *target-cpu* +* Has an optional double-precision FPU that also supports half-precision FP16 + values + * support is enabled by default with this *target-cpu* + * disable support using the `+soft-float` feature +* Has optional support for M-Profile Vector Extensions + * Also known as *Helium Technology* + * Available with only integer support, or both integer/float support + * The appropriate feature for the MVE is either `mve` (integer) or `mve.fp` + (float) + * `mve.fp` is enabled by default on this target CPU + * disable using `-mve.fp` (disable float MVE) or `-mve` (disable all MVE) + +### Arm Cortex-M85 + +The target CPU is `cortex-m85`. + +* Has DSP extensions + * support is controlled by the `dsp` *target-feature* + * enabled by default with this *target-cpu* +* Has an optional double-precision FPU that also supports half-precision FP16 + values + * support is enabled by default with this *target-cpu* + * disable support using the `+soft-float` feature +* Has optional support for M-Profile Vector Extensions + * Also known as *Helium Technology* + * Available with only integer support, or both integer/float support + * The appropriate feature for the MVE is either `mve` (integer) or `mve.fp` + (float) + * `mve.fp` is enabled by default on this target CPU + * disable using `-mve.fp` (disable float MVE) or `-mve` (disable all MVE) diff --git a/src/doc/rustc/src/platform-support/thumbv8m.main-none-eabihf.md b/src/doc/rustc/src/platform-support/thumbv8m.main-none-eabihf.md new file mode 100644 index 0000000000000..8f353a8d3db00 --- /dev/null +++ b/src/doc/rustc/src/platform-support/thumbv8m.main-none-eabihf.md @@ -0,0 +1,113 @@ +# `thumbv8m.main-none-eabihf` + +**Tier: 2** + +Bare-metal target for CPUs in the Mainline [ARMv8-M] architecture family, +supporting a subset of the [T32 ISA][t32-isa]. + +Processors in this family include the: + +* [Arm Cortex-M33F][cortex-m33] +* [Arm Cortex-M55F][cortex-m55] +* [Arm Cortex-M85F][cortex-m85] + +See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all +`arm-none-eabi` targets. + +This target uses the hard-float ABI: functions which take `f32` or `f64` as +arguments will have them passed via FPU registers. This target therefore +requires the use of an FPU (which is optional on Cortex-M33, Cortex-M55 and +Cortex-M85). See also the soft-float ABI version of this target +[`thumbv8m.main-none-eabi`](thumbv8m.main-none-eabi.md). + +[t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture +[ARMv8-M]: https://developer.arm.com/documentation/ddi0553/latest/ +[cortex-m33]: https://developer.arm.com/Processors/Cortex-M33 +[cortex-m55]: https://developer.arm.com/Processors/Cortex-M55 +[cortex-m85]: https://developer.arm.com/Processors/Cortex-M85 + +## Target maintainers + +* [Rust Embedded Devices Working Group Cortex-M + Team](https://github.com/rust-embedded), `cortex-m@teams.rust-embedded.org` + +## Target CPU and Target Feature options + +See [the bare-metal Arm +docs](arm-none-eabi.md#target-cpu-and-target-feature-options) for details on how +to use these flags. + +### Table of supported CPUs + +| CPU | FPU | DSP | MVE | Target CPU | Target Features | +| ----------- | --- | --- | --------- | ------------- | --------------------- | +| Cortex-M33 | SP | No | N/A | `cortex-m33` | `-dsp` | +| Cortex-M33 | SP | Yes | N/A | `cortex-m33` | None | +| Cortex-M33P | SP | No | N/A | `cortex-m35p` | `-dsp` | +| Cortex-M33P | SP | Yes | N/A | `cortex-m35p` | None | +| Cortex-M55 | DP | Yes | No | `cortex-m55` | `-mve` | +| Cortex-M55 | DP | Yes | Int | `cortex-m55` | `-mve.fp` | +| Cortex-M55 | DP | Yes | Int+Float | `cortex-m55` | None | +| Cortex-M85 | DP | Yes | No | `cortex-m85` | `-mve` | +| Cortex-M85 | DP | Yes | Int | `cortex-m85` | `-mve.fp` | +| Cortex-M85 | DP | Yes | Int+Float | `cortex-m85` | None | + +### Arm Cortex-M33 + +The target CPU is `cortex-m33`. + +* Has optional DSP extensions + * support is controlled by the `dsp` *target-feature* + * enabled by default with this *target-cpu* +* Has an optional single precision FPU + * support is enabled by default with this *target-cpu* + * support is required when using the hard-float ABI + +### Arm Cortex-M35P + +The target CPU is `cortex-m35p`. + +* Has optional DSP extensions + * support is controlled by the `dsp` *target-feature* + * enabled by default with this *target-cpu* +* Has a single precision FPU + * support is enabled by default with this *target-cpu* + * support is required when using the hard-float ABI + +### Arm Cortex-M55 + +The target CPU is `cortex-m55`. + +* Has DSP extensions + * support is controlled by the `dsp` *target-feature* + * enabled by default with this *target-cpu* +* Has an optional double-precision FPU that also supports half-precision FP16 + values + * support is enabled by default with this *target-cpu* + * support is required when using the hard-float ABI +* Has optional support for M-Profile Vector Extensions + * Also known as *Helium Technology* + * Available with only integer support, or both integer/float support + * The appropriate feature for the MVE is either `mve` (integer) or `mve.fp` + (float) + * `mve.fp` is enabled by default on this target CPU + * disable using `-mve.fp` (disable float MVE) or `-mve` (disable all MVE) + +### Arm Cortex-M85 + +The target CPU is `cortex-m85`. + +* Has DSP extensions + * support is controlled by the `dsp` *target-feature* + * enabled by default with this *target-cpu* +* Has an optional double-precision FPU that also supports half-precision FP16 + values + * support is enabled by default with this *target-cpu* + * support is required when using the hard-float ABI +* Has optional support for M-Profile Vector Extensions + * Also known as *Helium Technology* + * Available with only integer support, or both integer/float support + * The appropriate feature for the MVE is either `mve` (integer) or `mve.fp` + (float) + * `mve.fp` is enabled by default on this target CPU + * disable using `-mve.fp` (disable float MVE) or `-mve` (disable all MVE) From b17398490b0a6cb6b99cbf0d192e2952ae4f4b9b Mon Sep 17 00:00:00 2001 From: Jonathan Pallant Date: Fri, 26 Apr 2024 15:54:27 +0100 Subject: [PATCH 2/8] Fixed some typographical errors in arm-none-eabi.md. --- src/doc/rustc/src/platform-support/arm-none-eabi.md | 6 +++--- 1 file changed, 3 insertions(+), 3 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 de41c5e676a8d..4bd1d68fb755e 100644 --- a/src/doc/rustc/src/platform-support/arm-none-eabi.md +++ b/src/doc/rustc/src/platform-support/arm-none-eabi.md @@ -43,7 +43,7 @@ FPU support. If a target ends if `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 target therefore require the use of an FPU and will assume the +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 generated if the code is compiled with a `target-cpu` or `target-feature` option @@ -66,10 +66,10 @@ scheduling and support for the features you do have. More details are available in the detailed target-specific documentation. **Note:** Many target-features are currently unstable and subject to change, and -if you use them you should dissassmble the compiler output and manually inspect +if you use them you should disassemble the compiler output and manually inspect it to ensure only appropriate instructions for your CPU have been generated. -If do you wish to use the *target-cpu* and *target-feature* options, you can add +If you wish to use the *target-cpu* and *target-feature* options, you can add them to your `.cargo/config.toml` file alongside any other flags your project uses (likely linker related ones): From e6f0e03e5fec367d1a71a696238b210531ea9d51 Mon Sep 17 00:00:00 2001 From: Jonathan Pallant Date: Mon, 29 Apr 2024 09:42:50 +0100 Subject: [PATCH 3/8] Adding new arm target docs to SUMMARY.md --- src/doc/rustc/src/SUMMARY.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md index 31096b6df92b2..9dd68555bbe10 100644 --- a/src/doc/rustc/src/SUMMARY.md +++ b/src/doc/rustc/src/SUMMARY.md @@ -55,6 +55,13 @@ - [riscv32imac-unknown-xous-elf](platform-support/riscv32imac-unknown-xous-elf.md) - [riscv32*-unknown-none-elf](platform-support/riscv32-unknown-none-elf.md) - [sparc-unknown-none-elf](./platform-support/sparc-unknown-none-elf.md) + - [thumbv6m-none-eabi](./platform-support/thumbv6m-none-eabi.md) + - [thumbv7m-none-eabi](./platform-support/thumbv7m-none-eabi.md) + - [thumbv7em-none-eabi](./platform-support/thumbv7em-none-eabi.md) + - [thumbv7em-none-eabihf](./platform-support/thumbv7em-none-eabihf.md) + - [thumbv8m.base-none-eabi](./platform-support/thumbv8m.base-none-eabi.md) + - [thumbv8m.main-none-eabi](./platform-support/thumbv8m.main-none-eabi.md) + - [thumbv8m.main-none-eabihf](./platform-support/thumbv8m.main-none-eabihf.md) - [*-pc-windows-gnullvm](platform-support/pc-windows-gnullvm.md) - [\*-nto-qnx-\*](platform-support/nto-qnx.md) - [*-unikraft-linux-musl](platform-support/unikraft-linux-musl.md) From a9022d4680cfa60d56aa240f093c65b7dd99481f Mon Sep 17 00:00:00 2001 From: Jonathan Pallant Date: Mon, 29 Apr 2024 10:13:42 +0100 Subject: [PATCH 4/8] 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 From fa6b90cb8a9c7c5f437653040b6d1faf590ad5d9 Mon Sep 17 00:00:00 2001 From: Jonathan Pallant Date: Mon, 29 Apr 2024 10:32:04 +0100 Subject: [PATCH 5/8] arm target docs: collapsed eabi and eabihf into one --- src/doc/rustc/src/SUMMARY.md | 6 +- src/doc/rustc/src/platform-support.md | 4 +- .../src/platform-support/arm-none-eabi.md | 4 +- .../platform-support/thumbv7em-none-eabi.md | 28 +++-- .../platform-support/thumbv7em-none-eabihf.md | 67 ----------- .../thumbv8m.main-none-eabi.md | 57 +++++---- .../thumbv8m.main-none-eabihf.md | 113 ------------------ 7 files changed, 56 insertions(+), 223 deletions(-) delete mode 100644 src/doc/rustc/src/platform-support/thumbv7em-none-eabihf.md delete mode 100644 src/doc/rustc/src/platform-support/thumbv8m.main-none-eabihf.md diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md index 9dd68555bbe10..a3de28f801506 100644 --- a/src/doc/rustc/src/SUMMARY.md +++ b/src/doc/rustc/src/SUMMARY.md @@ -57,11 +57,9 @@ - [sparc-unknown-none-elf](./platform-support/sparc-unknown-none-elf.md) - [thumbv6m-none-eabi](./platform-support/thumbv6m-none-eabi.md) - [thumbv7m-none-eabi](./platform-support/thumbv7m-none-eabi.md) - - [thumbv7em-none-eabi](./platform-support/thumbv7em-none-eabi.md) - - [thumbv7em-none-eabihf](./platform-support/thumbv7em-none-eabihf.md) + - [thumbv7em-none-eabi\*](./platform-support/thumbv7em-none-eabi.md) - [thumbv8m.base-none-eabi](./platform-support/thumbv8m.base-none-eabi.md) - - [thumbv8m.main-none-eabi](./platform-support/thumbv8m.main-none-eabi.md) - - [thumbv8m.main-none-eabihf](./platform-support/thumbv8m.main-none-eabihf.md) + - [thumbv8m.main-none-eabi\*](./platform-support/thumbv8m.main-none-eabi.md) - [*-pc-windows-gnullvm](platform-support/pc-windows-gnullvm.md) - [\*-nto-qnx-\*](platform-support/nto-qnx.md) - [*-unikraft-linux-musl](platform-support/unikraft-linux-musl.md) diff --git a/src/doc/rustc/src/platform-support.md b/src/doc/rustc/src/platform-support.md index 526b5a5978995..cdab3d4401efe 100644 --- a/src/doc/rustc/src/platform-support.md +++ b/src/doc/rustc/src/platform-support.md @@ -180,13 +180,13 @@ target | std | notes `sparcv9-sun-solaris` | ✓ | SPARC Solaris 11, illumos [`thumbv6m-none-eabi`](platform-support/thumbv6m-none-eabi.md) | * | Bare ARMv6-M [`thumbv7em-none-eabi`](platform-support/thumbv7em-none-eabi.md) | * | Bare ARMv7E-M -[`thumbv7em-none-eabihf`](platform-support/thumbv7em-none-eabihf.md) | * | Bare ARMV7E-M, hardfloat +[`thumbv7em-none-eabihf`](platform-support/thumbv7em-none-eabi.md) | * | Bare ARMV7E-M, hardfloat [`thumbv7m-none-eabi`](platform-support/thumbv7m-none-eabi.md) | * | Bare ARMv7-M [`thumbv7neon-linux-androideabi`](platform-support/android.md) | ✓ | Thumb2-mode ARMv7-A Android with NEON `thumbv7neon-unknown-linux-gnueabihf` | ✓ | Thumb2-mode ARMv7-A Linux with NEON (kernel 4.4, glibc 2.23) [`thumbv8m.base-none-eabi`](platform-support/thumbv8m.base-none-eabi.md) | * | Bare ARMv8-M Baseline [`thumbv8m.main-none-eabi`](platform-support/thumbv8m.main-none-eabi.md) | * | Bare ARMv8-M Mainline -[`thumbv8m.main-none-eabihf`](platform-support/thumbv8m.main-none-eabihf.md) | * | Bare ARMv8-M Mainline, hardfloat +[`thumbv8m.main-none-eabihf`](platform-support/thumbv8m.main-none-eabi.md) | * | Bare ARMv8-M Mainline, hardfloat `wasm32-unknown-emscripten` | ✓ | WebAssembly via Emscripten `wasm32-unknown-unknown` | ✓ | WebAssembly `wasm32-wasi` | ✓ | WebAssembly with WASI (undergoing a [rename to `wasm32-wasip1`][wasi-rename]) 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 55d2f50b76213..64ae601723809 100644 --- a/src/doc/rustc/src/platform-support/arm-none-eabi.md +++ b/src/doc/rustc/src/platform-support/arm-none-eabi.md @@ -10,9 +10,9 @@ - Arm M-Profile Architectures - [`thumbv6m-none-eabi`](thumbv6m-none-eabi.md) - [`thumbv7m-none-eabi`](thumbv7m-none-eabi.md) - - [`thumbv7em-none-eabi`](thumbv7em-none-eabi.md) and [`thumbv7em-none-eabihf`](thumbv7em-none-eabihf.md) + - [`thumbv7em-none-eabi` and `thumbv7em-none-eabihf`](thumbv7em-none-eabi.md) - [`thumbv8m.base-none-eabi`](thumbv8m.base-none-eabi.md) - - [`thumbv8m.main-none-eabi`](thumbv8m.main-none-eabi.md) and [`thumbv8m.main-none-eabihf`](thumbv8m.main-none-eabihf.md) + - [`thumbv8m.main-none-eabi` and `thumbv8m.main-none-eabihf`](thumbv8m.main-none-eabi.md) - *Legacy* Arm Architectures - None 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 78a431fec9339..698c8ae7a6551 100644 --- a/src/doc/rustc/src/platform-support/thumbv7em-none-eabi.md +++ b/src/doc/rustc/src/platform-support/thumbv7em-none-eabi.md @@ -1,4 +1,4 @@ -# `thumbv7em-none-eabi` +# `thumbv7em-none-eabi` and `thumbv7em-none-eabihf` **Tier: 2** @@ -11,14 +11,8 @@ Processors in this family include the: * [Arm Cortex-M7][cortex-m7] and Arm Cortex-M7F 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 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 -[`thumbv7em-none-eabihf`](thumbv7em-none-eabihf.md). +`arm-none-eabi` targets, in particular the difference between the `eabi` and +`eabihf` ABI. [t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture [ARMv7E-M]: https://developer.arm.com/documentation/ddi0403/latest/ @@ -36,16 +30,26 @@ See [the bare-metal Arm docs](arm-none-eabi.md#target-cpu-and-target-feature-options) for details on how to use these flags. -### Table of supported CPUs +### Table of supported CPUs for `thumbv7em-none-eabi` | CPU | FPU | DSP | Target CPU | Target Features | | ---------- | --- | --- | ----------- | --------------- | +| Any | No | Yes | None | None | | Cortex-M4 | No | Yes | `cortex-m4` | `+soft-float` | | Cortex-M4F | SP | Yes | `cortex-m4` | None | | Cortex-M7 | No | Yes | `cortex-m7` | `+soft-float` | | Cortex-M7F | SP | Yes | `cortex-m7` | `-fp64` | | Cortex-M7F | DP | Yes | `cortex-m7` | None | +### Table of supported CPUs for `thumbv7em-none-eabihf` + +| CPU | FPU | DSP | Target CPU | Target Features | +| ---------- | --- | --- | ----------- | --------------- | +| Any | SP | Yes | None | None | +| Cortex-M4F | SP | Yes | `cortex-m4` | None | +| Cortex-M7F | SP | Yes | `cortex-m7` | `-fp64` | +| Cortex-M7F | DP | Yes | `cortex-m7` | None | + ### Arm Cortex-M4 and Arm Cortex-M4F The target CPU is `cortex-m4`. @@ -55,7 +59,7 @@ The target CPU is `cortex-m4`. * 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 + * disable support using the `+soft-float` feature (`eabi` only) ### Arm Cortex-M7 and Arm Cortex-M7F @@ -67,4 +71,4 @@ The target CPU is `cortex-m7`. * 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* - * disable support entirely using the `+soft-float` feature + * disable support entirely using the `+soft-float` feature (`eabi` only) diff --git a/src/doc/rustc/src/platform-support/thumbv7em-none-eabihf.md b/src/doc/rustc/src/platform-support/thumbv7em-none-eabihf.md deleted file mode 100644 index d4c93e3197c79..0000000000000 --- a/src/doc/rustc/src/platform-support/thumbv7em-none-eabihf.md +++ /dev/null @@ -1,67 +0,0 @@ -# `thumbv7em-none-eabihf` - -**Tier: 2** - -Bare-metal target for CPUs in the [ARMv7E-M] architecture family that have an -FPU, supporting a subset of the [T32 ISA][t32-isa]. - -Processors in this family include the: - -* [Arm Cortex-M4F][cortex-m4] -* [Arm Cortex-M7F][cortex-m7] - -See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all -`arm-none-eabi` targets. - -This target uses the hard-float ABI: functions which take `f32` or `f64` as -arguments will have them passed via FPU registers. This target therefore -requires the use of an FPU (which is optional on Cortex-M4 and Cortex-M7). See -also the soft-float ABI version of this target -[`thumbv7em-none-eabi`](thumbv7em-none-eabi.md). - -[t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture -[ARMv7E-M]: https://developer.arm.com/documentation/ddi0403/latest/ -[cortex-m4]: https://developer.arm.com/Processors/Cortex-M4 -[cortex-m7]: https://developer.arm.com/Processors/Cortex-M7 - -## Target maintainers - -* [Rust Embedded Devices Working Group Cortex-M - Team](https://github.com/rust-embedded), `cortex-m@teams.rust-embedded.org` - -## Target CPU and Target Feature options - -See [the bare-metal Arm -docs](arm-none-eabi.md#target-cpu-and-target-feature-options) for details on how -to use these flags. - -### Table of supported CPUs - -| CPU | FPU | DSP | Target CPU | Target Features | -| ---------- | --- | --- | ----------- | --------------- | -| Cortex-M4F | SP | Yes | `cortex-m4` | None | -| Cortex-M7F | SP | Yes | `cortex-m7` | `-fp64` | -| Cortex-M7F | DP | Yes | `cortex-m7` | None | - -### Arm Cortex-M4 and Arm Cortex-M4F - -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* -* Cortex-M4F has a single precision FPU - * support is enabled by default with this *target* - * support is required when using the hard-float ABI - -### Arm Cortex-M7 and Arm Cortex-M7F - -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* -* Cortex-M7F have either a single-precision or double-precision FPU - * single precision support is enabled by default with this *target* - * 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/thumbv8m.main-none-eabi.md b/src/doc/rustc/src/platform-support/thumbv8m.main-none-eabi.md index cbac897390e86..9541e1d582c23 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 @@ -1,4 +1,4 @@ -# `thumbv8m.main-none-eabi` +# `thumbv8m.main-none-eabi` and `thumbv8m.main-none-eabihf` **Tier: 2** @@ -13,14 +13,8 @@ Processors in this family include the: * [Arm Cortex-M85][cortex-m85] 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 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 -[`thumbv8m.main-none-eabihf`](thumbv7em-none-eabihf.md). +`arm-none-eabi` targets, in particular the difference between the `eabi` and +`eabihf` ABI. [t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture [ARMv8-M]: https://developer.arm.com/documentation/ddi0553/latest/ @@ -40,18 +34,19 @@ See [the bare-metal Arm docs](arm-none-eabi.md#target-cpu-and-target-feature-options) for details on how to use these flags. -### Table of supported CPUs +### Table of supported CPUs for `thumbv8m.main-none-eabi` | CPU | FPU | DSP | MVE | Target CPU | Target Features | | ----------- | --- | --- | --------- | ------------- | --------------------- | -| Cortex-M33 | No | No | N/A | `cortex-m33` | `+soft-float,-dsp` | -| Cortex-M33 | No | Yes | N/A | `cortex-m33` | `+soft-float` | -| Cortex-M33 | SP | No | N/A | `cortex-m33` | `-dsp` | -| Cortex-M33 | SP | Yes | N/A | `cortex-m33` | None | -| Cortex-M35P | No | No | N/A | `cortex-m35p` | `+soft-float,-dsp` | -| Cortex-M35P | No | Yes | N/A | `cortex-m35p` | `+soft-float` | -| Cortex-M35P | SP | No | N/A | `cortex-m35p` | `-dsp` | -| Cortex-M35P | SP | Yes | N/A | `cortex-m35p` | None | +| Unspecified | No | No | No | None | None | +| Cortex-M33 | No | No | No | `cortex-m33` | `+soft-float,-dsp` | +| Cortex-M33 | No | Yes | No | `cortex-m33` | `+soft-float` | +| Cortex-M33 | SP | No | No | `cortex-m33` | `-dsp` | +| Cortex-M33 | SP | Yes | No | `cortex-m33` | None | +| Cortex-M35P | No | No | No | `cortex-m35p` | `+soft-float,-dsp` | +| Cortex-M35P | No | Yes | No | `cortex-m35p` | `+soft-float` | +| Cortex-M35P | SP | No | No | `cortex-m35p` | `-dsp` | +| Cortex-M35P | SP | Yes | No | `cortex-m35p` | None | | Cortex-M55 | No | Yes | No | `cortex-m55` | `+soft-float,-mve` | | Cortex-M55 | DP | Yes | No | `cortex-m55` | `-mve` | | Cortex-M55 | No | Yes | Int | `cortex-m55` | `+soft-float,-mve.fp` | @@ -63,6 +58,22 @@ to use these flags. | Cortex-M85 | DP | Yes | Int | `cortex-m85` | `-mve.fp` | | Cortex-M85 | DP | Yes | Int+Float | `cortex-m85` | None | +### Table of supported CPUs for `thumbv8m.main-none-eabihf` + +| CPU | FPU | DSP | MVE | Target CPU | Target Features | +| ----------- | --- | --- | --------- | ------------- | --------------------- | +| Unspecified | SP | No | No | None | None | +| Cortex-M33 | SP | No | No | `cortex-m33` | `-dsp` | +| Cortex-M33 | SP | Yes | No | `cortex-m33` | None | +| Cortex-M33P | SP | No | No | `cortex-m35p` | `-dsp` | +| Cortex-M33P | SP | Yes | No | `cortex-m35p` | None | +| Cortex-M55 | DP | Yes | No | `cortex-m55` | `-mve` | +| Cortex-M55 | DP | Yes | Int | `cortex-m55` | `-mve.fp` | +| Cortex-M55 | DP | Yes | Int+Float | `cortex-m55` | None | +| Cortex-M85 | DP | Yes | No | `cortex-m85` | `-mve` | +| Cortex-M85 | DP | Yes | Int | `cortex-m85` | `-mve.fp` | +| Cortex-M85 | DP | Yes | Int+Float | `cortex-m85` | None | + ### Arm Cortex-M33 The target CPU is `cortex-m33`. @@ -72,7 +83,7 @@ The target CPU is `cortex-m33`. * enabled by default with this *target-cpu* * Has an optional single precision FPU * support is enabled by default with this *target-cpu* - * disable support using the `+soft-float` feature + * disable support using the `+soft-float` feature (`eabi` only) ### Arm Cortex-M35P @@ -81,9 +92,9 @@ The target CPU is `cortex-m35p`. * Has optional DSP extensions * support is controlled by the `dsp` *target-feature* * enabled by default with this *target-cpu* -* Has a single precision FPU +* Has an optional single precision FPU * support is enabled by default with this *target-cpu* - * disable support using the `+soft-float` feature + * disable support using the `+soft-float` feature (`eabi` only) ### Arm Cortex-M55 @@ -95,7 +106,7 @@ The target CPU is `cortex-m55`. * Has an optional double-precision FPU that also supports half-precision FP16 values * support is enabled by default with this *target-cpu* - * disable support using the `+soft-float` feature + * disable support using the `+soft-float` feature (`eabi` only) * Has optional support for M-Profile Vector Extensions * Also known as *Helium Technology* * Available with only integer support, or both integer/float support @@ -114,7 +125,7 @@ The target CPU is `cortex-m85`. * Has an optional double-precision FPU that also supports half-precision FP16 values * support is enabled by default with this *target-cpu* - * disable support using the `+soft-float` feature + * disable support using the `+soft-float` feature (`eabi` only) * Has optional support for M-Profile Vector Extensions * Also known as *Helium Technology* * Available with only integer support, or both integer/float support diff --git a/src/doc/rustc/src/platform-support/thumbv8m.main-none-eabihf.md b/src/doc/rustc/src/platform-support/thumbv8m.main-none-eabihf.md deleted file mode 100644 index 8f353a8d3db00..0000000000000 --- a/src/doc/rustc/src/platform-support/thumbv8m.main-none-eabihf.md +++ /dev/null @@ -1,113 +0,0 @@ -# `thumbv8m.main-none-eabihf` - -**Tier: 2** - -Bare-metal target for CPUs in the Mainline [ARMv8-M] architecture family, -supporting a subset of the [T32 ISA][t32-isa]. - -Processors in this family include the: - -* [Arm Cortex-M33F][cortex-m33] -* [Arm Cortex-M55F][cortex-m55] -* [Arm Cortex-M85F][cortex-m85] - -See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all -`arm-none-eabi` targets. - -This target uses the hard-float ABI: functions which take `f32` or `f64` as -arguments will have them passed via FPU registers. This target therefore -requires the use of an FPU (which is optional on Cortex-M33, Cortex-M55 and -Cortex-M85). See also the soft-float ABI version of this target -[`thumbv8m.main-none-eabi`](thumbv8m.main-none-eabi.md). - -[t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture -[ARMv8-M]: https://developer.arm.com/documentation/ddi0553/latest/ -[cortex-m33]: https://developer.arm.com/Processors/Cortex-M33 -[cortex-m55]: https://developer.arm.com/Processors/Cortex-M55 -[cortex-m85]: https://developer.arm.com/Processors/Cortex-M85 - -## Target maintainers - -* [Rust Embedded Devices Working Group Cortex-M - Team](https://github.com/rust-embedded), `cortex-m@teams.rust-embedded.org` - -## Target CPU and Target Feature options - -See [the bare-metal Arm -docs](arm-none-eabi.md#target-cpu-and-target-feature-options) for details on how -to use these flags. - -### Table of supported CPUs - -| CPU | FPU | DSP | MVE | Target CPU | Target Features | -| ----------- | --- | --- | --------- | ------------- | --------------------- | -| Cortex-M33 | SP | No | N/A | `cortex-m33` | `-dsp` | -| Cortex-M33 | SP | Yes | N/A | `cortex-m33` | None | -| Cortex-M33P | SP | No | N/A | `cortex-m35p` | `-dsp` | -| Cortex-M33P | SP | Yes | N/A | `cortex-m35p` | None | -| Cortex-M55 | DP | Yes | No | `cortex-m55` | `-mve` | -| Cortex-M55 | DP | Yes | Int | `cortex-m55` | `-mve.fp` | -| Cortex-M55 | DP | Yes | Int+Float | `cortex-m55` | None | -| Cortex-M85 | DP | Yes | No | `cortex-m85` | `-mve` | -| Cortex-M85 | DP | Yes | Int | `cortex-m85` | `-mve.fp` | -| Cortex-M85 | DP | Yes | Int+Float | `cortex-m85` | None | - -### Arm Cortex-M33 - -The target CPU is `cortex-m33`. - -* Has optional DSP extensions - * support is controlled by the `dsp` *target-feature* - * enabled by default with this *target-cpu* -* Has an optional single precision FPU - * support is enabled by default with this *target-cpu* - * support is required when using the hard-float ABI - -### Arm Cortex-M35P - -The target CPU is `cortex-m35p`. - -* Has optional DSP extensions - * support is controlled by the `dsp` *target-feature* - * enabled by default with this *target-cpu* -* Has a single precision FPU - * support is enabled by default with this *target-cpu* - * support is required when using the hard-float ABI - -### Arm Cortex-M55 - -The target CPU is `cortex-m55`. - -* Has DSP extensions - * support is controlled by the `dsp` *target-feature* - * enabled by default with this *target-cpu* -* Has an optional double-precision FPU that also supports half-precision FP16 - values - * support is enabled by default with this *target-cpu* - * support is required when using the hard-float ABI -* Has optional support for M-Profile Vector Extensions - * Also known as *Helium Technology* - * Available with only integer support, or both integer/float support - * The appropriate feature for the MVE is either `mve` (integer) or `mve.fp` - (float) - * `mve.fp` is enabled by default on this target CPU - * disable using `-mve.fp` (disable float MVE) or `-mve` (disable all MVE) - -### Arm Cortex-M85 - -The target CPU is `cortex-m85`. - -* Has DSP extensions - * support is controlled by the `dsp` *target-feature* - * enabled by default with this *target-cpu* -* Has an optional double-precision FPU that also supports half-precision FP16 - values - * support is enabled by default with this *target-cpu* - * support is required when using the hard-float ABI -* Has optional support for M-Profile Vector Extensions - * Also known as *Helium Technology* - * Available with only integer support, or both integer/float support - * The appropriate feature for the MVE is either `mve` (integer) or `mve.fp` - (float) - * `mve.fp` is enabled by default on this target CPU - * disable using `-mve.fp` (disable float MVE) or `-mve` (disable all MVE) From 8cea4f3e1e9892a39affd9d1fbfcf94aba11fae2 Mon Sep 17 00:00:00 2001 From: Jonathan Pallant Date: Mon, 29 Apr 2024 17:31:49 +0100 Subject: [PATCH 6/8] arm target docs: small wording fixes --- src/doc/rustc/src/platform-support/arm-none-eabi.md | 2 +- src/doc/rustc/src/platform-support/thumbv8m.base-none-eabi.md | 2 +- 2 files changed, 2 insertions(+), 2 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 64ae601723809..e7ffc23d28007 100644 --- a/src/doc/rustc/src/platform-support/arm-none-eabi.md +++ b/src/doc/rustc/src/platform-support/arm-none-eabi.md @@ -64,7 +64,7 @@ instructions. It is possible to tell Rust (or LLVM) that you have a specific model of Arm processor, using the [`-C target-cpu`][target-cpu] option. You can also control whether Rust (or LLVM) will include instructions that target optional hardware -features, e.g. hardware floating point, or vector maths operations, using [`-C +features, e.g. hardware floating-point, or Advanced SIMD operations, using [`-C target-feature`][target-feature]. It is important to note that selecting a *target-cpu* will typically enable 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 9733ce0e0aac9..c63620067acfd 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 @@ -14,7 +14,7 @@ See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all This target uses the soft-float ABI: functions which take `f32` or `f64` as arguments will have those values packed into integer registers. This is the -only option because there is no FPU support in [ARMv6-M]. +only option because there is no FPU support in [ARMv8-M] Baseline. [t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture [ARMv8-M]: https://developer.arm.com/documentation/ddi0553/latest/ From de0c02c9abaeae6e07241a7ea1d9e4fe049c2fc4 Mon Sep 17 00:00:00 2001 From: Jonathan Pallant Date: Mon, 29 Apr 2024 17:52:16 +0100 Subject: [PATCH 7/8] Recapitalise ARMvX{-Y} to ArmvX{-Y} Yes it looks weird, but this is how Arm write it now. I left ARM64 alone, because it's a Microsoft/Apple term but not an Arm term (they have Armv8-A and Armv9-A architectures, which say that A64 instructions are executed when in the Aarch64 state), and I don't want to get into that, especially for a Tier 1 target. --- src/doc/rustc/src/platform-support.md | 98 +++++++++---------- .../src/platform-support/arm-none-eabi.md | 2 +- .../armeb-unknown-linux-gnueabi.md | 10 +- .../src/platform-support/armv4t-none-eabi.md | 6 +- .../src/platform-support/armv5te-none-eabi.md | 6 +- .../platform-support/armv6k-nintendo-3ds.md | 2 +- .../armv7-unknown-linux-uclibceabi.md | 6 +- .../armv7-unknown-linux-uclibceabihf.md | 2 +- .../src/platform-support/armv7r-none-eabi.md | 2 +- .../platform-support/armv8r-none-eabihf.md | 2 +- .../platform-support/thumbv6m-none-eabi.md | 6 +- .../platform-support/thumbv7em-none-eabi.md | 4 +- .../platform-support/thumbv7m-none-eabi.md | 6 +- .../thumbv8m.base-none-eabi.md | 6 +- .../thumbv8m.main-none-eabi.md | 4 +- 15 files changed, 81 insertions(+), 81 deletions(-) diff --git a/src/doc/rustc/src/platform-support.md b/src/doc/rustc/src/platform-support.md index cdab3d4401efe..764798a80e6d2 100644 --- a/src/doc/rustc/src/platform-support.md +++ b/src/doc/rustc/src/platform-support.md @@ -89,9 +89,9 @@ target | notes `aarch64-apple-darwin` | ARM64 macOS (11.0+, Big Sur+) `aarch64-pc-windows-msvc` | ARM64 Windows MSVC `aarch64-unknown-linux-musl` | ARM64 Linux with musl 1.2.3 -`arm-unknown-linux-gnueabi` | ARMv6 Linux (kernel 3.2, glibc 2.17) -`arm-unknown-linux-gnueabihf` | ARMv6 Linux, hardfloat (kernel 3.2, glibc 2.17) -`armv7-unknown-linux-gnueabihf` | ARMv7-A Linux, hardfloat (kernel 3.2, glibc 2.17) +`arm-unknown-linux-gnueabi` | Armv6 Linux (kernel 3.2, glibc 2.17) +`arm-unknown-linux-gnueabihf` | Armv6 Linux, hardfloat (kernel 3.2, glibc 2.17) +`armv7-unknown-linux-gnueabihf` | Armv7-A Linux, hardfloat (kernel 3.2, glibc 2.17) [`loongarch64-unknown-linux-gnu`](platform-support/loongarch-linux.md) | LoongArch64 Linux, LP64D ABI (kernel 5.19, glibc 2.36) `powerpc-unknown-linux-gnu` | PowerPC Linux (kernel 3.2, glibc 2.17) `powerpc64-unknown-linux-gnu` | PPC64 Linux (kernel 3.2, glibc 2.17) @@ -143,21 +143,21 @@ target | std | notes `aarch64-unknown-none-softfloat` | * | Bare ARM64, softfloat `aarch64-unknown-none` | * | Bare ARM64, hardfloat [`aarch64-unknown-uefi`](platform-support/unknown-uefi.md) | ? | ARM64 UEFI -[`arm-linux-androideabi`](platform-support/android.md) | ✓ | ARMv6 Android -`arm-unknown-linux-musleabi` | ✓ | ARMv6 Linux with musl 1.2.3 -`arm-unknown-linux-musleabihf` | ✓ | ARMv6 Linux with musl 1.2.3, hardfloat -[`armebv7r-none-eabi`](platform-support/armv7r-none-eabi.md) | * | Bare ARMv7-R, Big Endian -[`armebv7r-none-eabihf`](platform-support/armv7r-none-eabi.md) | * | Bare ARMv7-R, Big Endian, hardfloat -`armv5te-unknown-linux-gnueabi` | ✓ | ARMv5TE Linux (kernel 4.4, glibc 2.23) -`armv5te-unknown-linux-musleabi` | ✓ | ARMv5TE Linux with musl 1.2.3 -[`armv7-linux-androideabi`](platform-support/android.md) | ✓ | ARMv7-A Android -`armv7-unknown-linux-gnueabi` | ✓ | ARMv7-A Linux (kernel 4.15, glibc 2.27) -`armv7-unknown-linux-musleabi` | ✓ | ARMv7-A Linux with musl 1.2.3 -`armv7-unknown-linux-musleabihf` | ✓ | ARMv7-A Linux with musl 1.2.3, hardfloat -[`armv7-unknown-linux-ohos`](platform-support/openharmony.md) | ✓ | ARMv7-A OpenHarmony -[`armv7a-none-eabi`](platform-support/arm-none-eabi.md) | * | Bare ARMv7-A -[`armv7r-none-eabi`](platform-support/armv7r-none-eabi.md) | * | Bare ARMv7-R -[`armv7r-none-eabihf`](platform-support/armv7r-none-eabi.md) | * | Bare ARMv7-R, hardfloat +[`arm-linux-androideabi`](platform-support/android.md) | ✓ | Armv6 Android +`arm-unknown-linux-musleabi` | ✓ | Armv6 Linux with musl 1.2.3 +`arm-unknown-linux-musleabihf` | ✓ | Armv6 Linux with musl 1.2.3, hardfloat +[`armebv7r-none-eabi`](platform-support/armv7r-none-eabi.md) | * | Bare Armv7-R, Big Endian +[`armebv7r-none-eabihf`](platform-support/armv7r-none-eabi.md) | * | Bare Armv7-R, Big Endian, hardfloat +`armv5te-unknown-linux-gnueabi` | ✓ | Armv5TE Linux (kernel 4.4, glibc 2.23) +`armv5te-unknown-linux-musleabi` | ✓ | Armv5TE Linux with musl 1.2.3 +[`armv7-linux-androideabi`](platform-support/android.md) | ✓ | Armv7-A Android +`armv7-unknown-linux-gnueabi` | ✓ | Armv7-A Linux (kernel 4.15, glibc 2.27) +`armv7-unknown-linux-musleabi` | ✓ | Armv7-A Linux with musl 1.2.3 +`armv7-unknown-linux-musleabihf` | ✓ | Armv7-A Linux with musl 1.2.3, hardfloat +[`armv7-unknown-linux-ohos`](platform-support/openharmony.md) | ✓ | Armv7-A OpenHarmony +[`armv7a-none-eabi`](platform-support/arm-none-eabi.md) | * | Bare Armv7-A +[`armv7r-none-eabi`](platform-support/armv7r-none-eabi.md) | * | Bare Armv7-R +[`armv7r-none-eabihf`](platform-support/armv7r-none-eabi.md) | * | Bare Armv7-R, hardfloat `i586-pc-windows-msvc` | * | 32-bit Windows w/o SSE [^x86_32-floats-x87] `i586-unknown-linux-gnu` | ✓ | 32-bit Linux w/o SSE (kernel 3.2, glibc 2.17) [^x86_32-floats-x87] `i586-unknown-linux-musl` | ✓ | 32-bit Linux w/o SSE, musl 1.2.3 [^x86_32-floats-x87] @@ -178,15 +178,15 @@ target | std | notes `riscv64imac-unknown-none-elf` | * | Bare RISC-V (RV64IMAC ISA) `sparc64-unknown-linux-gnu` | ✓ | SPARC Linux (kernel 4.4, glibc 2.23) `sparcv9-sun-solaris` | ✓ | SPARC Solaris 11, illumos -[`thumbv6m-none-eabi`](platform-support/thumbv6m-none-eabi.md) | * | Bare ARMv6-M -[`thumbv7em-none-eabi`](platform-support/thumbv7em-none-eabi.md) | * | Bare ARMv7E-M -[`thumbv7em-none-eabihf`](platform-support/thumbv7em-none-eabi.md) | * | Bare ARMV7E-M, hardfloat -[`thumbv7m-none-eabi`](platform-support/thumbv7m-none-eabi.md) | * | Bare ARMv7-M -[`thumbv7neon-linux-androideabi`](platform-support/android.md) | ✓ | Thumb2-mode ARMv7-A Android with NEON -`thumbv7neon-unknown-linux-gnueabihf` | ✓ | Thumb2-mode ARMv7-A Linux with NEON (kernel 4.4, glibc 2.23) -[`thumbv8m.base-none-eabi`](platform-support/thumbv8m.base-none-eabi.md) | * | Bare ARMv8-M Baseline -[`thumbv8m.main-none-eabi`](platform-support/thumbv8m.main-none-eabi.md) | * | Bare ARMv8-M Mainline -[`thumbv8m.main-none-eabihf`](platform-support/thumbv8m.main-none-eabi.md) | * | Bare ARMv8-M Mainline, hardfloat +[`thumbv6m-none-eabi`](platform-support/thumbv6m-none-eabi.md) | * | Bare Armv6-M +[`thumbv7em-none-eabi`](platform-support/thumbv7em-none-eabi.md) | * | Bare Armv7E-M +[`thumbv7em-none-eabihf`](platform-support/thumbv7em-none-eabi.md) | * | Bare Armv7E-M, hardfloat +[`thumbv7m-none-eabi`](platform-support/thumbv7m-none-eabi.md) | * | Bare Armv7-M +[`thumbv7neon-linux-androideabi`](platform-support/android.md) | ✓ | Thumb2-mode Armv7-A Android with NEON +`thumbv7neon-unknown-linux-gnueabihf` | ✓ | Thumb2-mode Armv7-A Linux with NEON (kernel 4.4, glibc 2.23) +[`thumbv8m.base-none-eabi`](platform-support/thumbv8m.base-none-eabi.md) | * | Bare Armv8-M Baseline +[`thumbv8m.main-none-eabi`](platform-support/thumbv8m.main-none-eabi.md) | * | Bare Armv8-M Mainline +[`thumbv8m.main-none-eabihf`](platform-support/thumbv8m.main-none-eabi.md) | * | Bare Armv8-M Mainline, hardfloat `wasm32-unknown-emscripten` | ✓ | WebAssembly via Emscripten `wasm32-unknown-unknown` | ✓ | WebAssembly `wasm32-wasi` | ✓ | WebAssembly with WASI (undergoing a [rename to `wasm32-wasip1`][wasi-rename]) @@ -264,27 +264,27 @@ target | std | host | notes `aarch64_be-unknown-linux-gnu_ilp32` | ✓ | ✓ | ARM64 Linux (big-endian, ILP32 ABI) `aarch64_be-unknown-linux-gnu` | ✓ | ✓ | ARM64 Linux (big-endian) [`aarch64_be-unknown-netbsd`](platform-support/netbsd.md) | ✓ | ✓ | ARM64 NetBSD (big-endian) -[`arm64_32-apple-watchos`](platform-support/apple-watchos.md) | ✓ | | ARM Apple WatchOS 64-bit with 32-bit pointers -[`armeb-unknown-linux-gnueabi`](platform-support/armeb-unknown-linux-gnueabi.md) | ✓ | ? | ARM BE8 the default ARM big-endian architecture since [ARMv6](https://developer.arm.com/documentation/101754/0616/armlink-Reference/armlink-Command-line-Options/--be8?lang=en). -[`armv4t-none-eabi`](platform-support/armv4t-none-eabi.md) | * | | Bare ARMv4T -`armv4t-unknown-linux-gnueabi` | ? | | ARMv4T Linux -[`armv5te-none-eabi`](platform-support/armv5te-none-eabi.md) | * | | Bare ARMv5TE -`armv5te-unknown-linux-uclibceabi` | ? | | ARMv5TE Linux with uClibc -`armv6-unknown-freebsd` | ✓ | ✓ | ARMv6 FreeBSD -[`armv6-unknown-netbsd-eabihf`](platform-support/netbsd.md) | ✓ | ✓ | ARMv6 NetBSD w/hard-float -[`armv6k-nintendo-3ds`](platform-support/armv6k-nintendo-3ds.md) | ? | | ARMv6K Nintendo 3DS, Horizon (Requires devkitARM toolchain) -[`armv7-sony-vita-newlibeabihf`](platform-support/armv7-sony-vita-newlibeabihf.md) | ✓ | | ARMv7-A Cortex-A9 Sony PlayStation Vita (requires VITASDK toolchain) -[`armv7-unknown-linux-uclibceabi`](platform-support/armv7-unknown-linux-uclibceabi.md) | ✓ | ✓ | ARMv7-A Linux with uClibc, softfloat -[`armv7-unknown-linux-uclibceabihf`](platform-support/armv7-unknown-linux-uclibceabihf.md) | ✓ | ? | ARMv7-A Linux with uClibc, hardfloat -`armv7-unknown-freebsd` | ✓ | ✓ | ARMv7-A FreeBSD -[`armv7-unknown-netbsd-eabihf`](platform-support/netbsd.md) | ✓ | ✓ | ARMv7-A NetBSD w/hard-float -`armv7-wrs-vxworks-eabihf` | ? | | ARMv7-A for VxWorks +[`arm64_32-apple-watchos`](platform-support/apple-watchos.md) | ✓ | | Arm Apple WatchOS 64-bit with 32-bit pointers +[`armeb-unknown-linux-gnueabi`](platform-support/armeb-unknown-linux-gnueabi.md) | ✓ | ? | Arm BE8 the default Arm big-endian architecture since [Armv6](https://developer.arm.com/documentation/101754/0616/armlink-Reference/armlink-Command-line-Options/--be8?lang=en). +[`armv4t-none-eabi`](platform-support/armv4t-none-eabi.md) | * | | Bare Armv4T +`armv4t-unknown-linux-gnueabi` | ? | | Armv4T Linux +[`armv5te-none-eabi`](platform-support/armv5te-none-eabi.md) | * | | Bare Armv5TE +`armv5te-unknown-linux-uclibceabi` | ? | | Armv5TE Linux with uClibc +`armv6-unknown-freebsd` | ✓ | ✓ | Armv6 FreeBSD +[`armv6-unknown-netbsd-eabihf`](platform-support/netbsd.md) | ✓ | ✓ | Armv6 NetBSD w/hard-float +[`armv6k-nintendo-3ds`](platform-support/armv6k-nintendo-3ds.md) | ? | | Armv6k Nintendo 3DS, Horizon (Requires devkitARM toolchain) +[`armv7-sony-vita-newlibeabihf`](platform-support/armv7-sony-vita-newlibeabihf.md) | ✓ | | Armv7-A Cortex-A9 Sony PlayStation Vita (requires VITASDK toolchain) +[`armv7-unknown-linux-uclibceabi`](platform-support/armv7-unknown-linux-uclibceabi.md) | ✓ | ✓ | Armv7-A Linux with uClibc, softfloat +[`armv7-unknown-linux-uclibceabihf`](platform-support/armv7-unknown-linux-uclibceabihf.md) | ✓ | ? | Armv7-A Linux with uClibc, hardfloat +`armv7-unknown-freebsd` | ✓ | ✓ | Armv7-A FreeBSD +[`armv7-unknown-netbsd-eabihf`](platform-support/netbsd.md) | ✓ | ✓ | Armv7-A NetBSD w/hard-float +`armv7-wrs-vxworks-eabihf` | ? | | Armv7-A for VxWorks [`armv7a-kmc-solid_asp3-eabi`](platform-support/kmc-solid.md) | ✓ | | ARM SOLID with TOPPERS/ASP3 [`armv7a-kmc-solid_asp3-eabihf`](platform-support/kmc-solid.md) | ✓ | | ARM SOLID with TOPPERS/ASP3, hardfloat -[`armv7a-none-eabihf`](platform-support/arm-none-eabi.md) | * | | Bare ARMv7-A, hardfloat -[`armv7k-apple-watchos`](platform-support/apple-watchos.md) | ✓ | | ARMv7-A Apple WatchOS -`armv7s-apple-ios` | ✓ | | ARMv7-A Apple-A6 Apple iOS -[`armv8r-none-eabihf`](platform-support/armv8r-none-eabihf.md) | * | | Bare ARMv8-R, hardfloat +[`armv7a-none-eabihf`](platform-support/arm-none-eabi.md) | * | | Bare Armv7-A, hardfloat +[`armv7k-apple-watchos`](platform-support/apple-watchos.md) | ✓ | | Armv7-A Apple WatchOS +`armv7s-apple-ios` | ✓ | | Armv7-A Apple-A6 Apple iOS +[`armv8r-none-eabihf`](platform-support/armv8r-none-eabihf.md) | * | | Bare Armv8-R, hardfloat `avr-unknown-gnu-atmega328` | * | | AVR. Requires `-Z build-std=core` `bpfeb-unknown-none` | * | | BPF (big endian) `bpfel-unknown-none` | * | | BPF (little endian) @@ -360,11 +360,11 @@ target | std | host | notes [`sparc-unknown-none-elf`](./platform-support/sparc-unknown-none-elf.md) | * | | Bare 32-bit SPARC V7+ [`sparc64-unknown-netbsd`](platform-support/netbsd.md) | ✓ | ✓ | NetBSD/sparc64 [`sparc64-unknown-openbsd`](platform-support/openbsd.md) | ✓ | ✓ | OpenBSD/sparc64 -[`thumbv4t-none-eabi`](platform-support/armv4t-none-eabi.md) | * | | Thumb-mode Bare ARMv4T -[`thumbv5te-none-eabi`](platform-support/armv5te-none-eabi.md) | * | | Thumb-mode Bare ARMv5TE +[`thumbv4t-none-eabi`](platform-support/armv4t-none-eabi.md) | * | | Thumb-mode Bare Armv4T +[`thumbv5te-none-eabi`](platform-support/armv5te-none-eabi.md) | * | | Thumb-mode Bare Armv5TE `thumbv7a-pc-windows-msvc` | ? | | `thumbv7a-uwp-windows-msvc` | ✓ | | -`thumbv7neon-unknown-linux-musleabihf` | ? | | Thumb2-mode ARMv7-A Linux with NEON, musl 1.2.3 +`thumbv7neon-unknown-linux-musleabihf` | ? | | Thumb2-mode Armv7-A Linux with NEON, musl 1.2.3 [`wasm32-wasip2`](platform-support/wasm32-wasip2.md) | ✓ | | WebAssembly [`wasm64-unknown-unknown`](platform-support/wasm64-unknown-unknown.md) | ? | | WebAssembly `x86_64-apple-ios-macabi` | ✓ | | Apple Catalyst on x86_64 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 e7ffc23d28007..4560860b88baf 100644 --- a/src/doc/rustc/src/platform-support/arm-none-eabi.md +++ b/src/doc/rustc/src/platform-support/arm-none-eabi.md @@ -31,7 +31,7 @@ ## Common Target Details 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 +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*: diff --git a/src/doc/rustc/src/platform-support/armeb-unknown-linux-gnueabi.md b/src/doc/rustc/src/platform-support/armeb-unknown-linux-gnueabi.md index 32d3440f1dc98..e7e3fd01c4dc7 100644 --- a/src/doc/rustc/src/platform-support/armeb-unknown-linux-gnueabi.md +++ b/src/doc/rustc/src/platform-support/armeb-unknown-linux-gnueabi.md @@ -1,22 +1,22 @@ # armeb-unknown-linux-gnueabi **Tier: 3** -Target for cross-compiling Linux user-mode applications targeting the ARM BE8 architecture. +Target for cross-compiling Linux user-mode applications targeting the Arm BE8 architecture. ## Overview -BE8 architecture retains the same little-endian ordered code-stream used by conventional little endian ARM systems, however the data accesses are in big-endian. BE8 is used primarily in high-performance networking applications where the ability to read packets in their native "Network Byte Order" is important (many network protocols transmit data in big-endian byte order for their wire formats). +BE8 architecture retains the same little-endian ordered code-stream used by conventional little endian Arm systems, however the data accesses are in big-endian. BE8 is used primarily in high-performance networking applications where the ability to read packets in their native "Network Byte Order" is important (many network protocols transmit data in big-endian byte order for their wire formats). ## History -BE8 architecture is the default big-endian architecture for ARM since [ARMv6](https://developer.arm.com/documentation/101754/0616/armlink-Reference/armlink-Command-line-Options/--be8?lang=en). It's predecessor, used for ARMv4 and ARMv5 devices was [BE32](https://developer.arm.com/documentation/dui0474/j/linker-command-line-options/--be32). On ARMv6 architecture, endianness can be configured via [system registers](https://developer.arm.com/documentation/ddi0290/g/unaligned-and-mixed-endian-data-access-support/mixed-endian-access-support/interaction-between-the-bus-protocol-and-the-core-endianness). However, BE32 was withdrawn for [ARMv7](https://developer.arm.com/documentation/ddi0406/cb/Appendixes/Deprecated-and-Obsolete-Features/Obsolete-features/Support-for-BE-32-endianness-model) onwards. +BE8 architecture is the default big-endian architecture for Arm since [Armv6](https://developer.arm.com/documentation/101754/0616/armlink-Reference/armlink-Command-line-Options/--be8?lang=en). It's predecessor, used for Armv4 and Armv5 devices was [BE32](https://developer.arm.com/documentation/dui0474/j/linker-command-line-options/--be32). On Armv6 architecture, endianness can be configured via [system registers](https://developer.arm.com/documentation/ddi0290/g/unaligned-and-mixed-endian-data-access-support/mixed-endian-access-support/interaction-between-the-bus-protocol-and-the-core-endianness). However, BE32 was withdrawn for [Armv7](https://developer.arm.com/documentation/ddi0406/cb/Appendixes/Deprecated-and-Obsolete-Features/Obsolete-features/Support-for-BE-32-endianness-model) onwards. ## Target Maintainers * [@WorksButNotTested](https://github.com/WorksButNotTested) ## Requirements -The target is cross-compiled. This target supports `std` in the normal way (indeed only nominal changes are required from the standard ARM configuration). +The target is cross-compiled. This target supports `std` in the normal way (indeed only nominal changes are required from the standard Arm configuration). ## Target definition -The target definition can be seen [here](https://github.com/rust-lang/rust/tree/master/compiler/rustc_target/src/spec/armeb_unknown_linux_gnueabi.rs). In particular, it should be noted that the `features` specify that this target is built for the ARMv8 core. Though this can likely be modified as required. +The target definition can be seen [here](https://github.com/rust-lang/rust/tree/master/compiler/rustc_target/src/spec/armeb_unknown_linux_gnueabi.rs). In particular, it should be noted that the `features` specify that this target is built for the Armv8 core. Though this can likely be modified as required. ## Building the target Because it is Tier 3, rust does not yet ship pre-compiled artifacts for this target. diff --git a/src/doc/rustc/src/platform-support/armv4t-none-eabi.md b/src/doc/rustc/src/platform-support/armv4t-none-eabi.md index 29c47db8351c7..f4c8dd46f1d03 100644 --- a/src/doc/rustc/src/platform-support/armv4t-none-eabi.md +++ b/src/doc/rustc/src/platform-support/armv4t-none-eabi.md @@ -2,12 +2,12 @@ Tier 3 -Bare-metal target for any cpu in the ARMv4T architecture family, supporting -ARM/Thumb code interworking (aka `a32`/`t32`), with ARM code as the default code +Bare-metal target for any cpu in the Armv4T architecture family, supporting +ARM/Thumb code interworking (aka `A32`/`T32`), with ARM code as the default code generation. In particular this supports the Game Boy Advance (GBA), but there's nothing -GBA-specific with this target, so any ARMv4T device should work fine. +GBA-specific with this target, so any Armv4T device should work fine. See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all `arm-none-eabi` targets. diff --git a/src/doc/rustc/src/platform-support/armv5te-none-eabi.md b/src/doc/rustc/src/platform-support/armv5te-none-eabi.md index 37284ba720997..41621e070bb48 100644 --- a/src/doc/rustc/src/platform-support/armv5te-none-eabi.md +++ b/src/doc/rustc/src/platform-support/armv5te-none-eabi.md @@ -2,11 +2,11 @@ **Tier: 3** -Bare-metal target for any cpu in the ARMv5TE architecture family, supporting -ARM/Thumb code interworking (aka `a32`/`t32`), with `a32` code as the default code +Bare-metal target for any cpu in the Armv5TE architecture family, supporting +ARM/Thumb code interworking (aka `A32`/`T32`), with `A32` code as the default code generation. -The `thumbv5te-none-eabi` target is the same as this one, but the instruction set defaults to `t32`. +The `thumbv5te-none-eabi` target is the same as this one, but the instruction set defaults to `T32`. See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all `arm-none-eabi` targets. diff --git a/src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md b/src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md index 540e5a4af938e..160986aeae94f 100644 --- a/src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md +++ b/src/doc/rustc/src/platform-support/armv6k-nintendo-3ds.md @@ -2,7 +2,7 @@ **Tier: 3** -The Nintendo 3DS platform, which has an ARMv6K processor, and its associated +The Nintendo 3DS platform, which has an Armv6k processor, and its associated operating system (`horizon`). Rust support for this target is not affiliated with Nintendo, and is not derived diff --git a/src/doc/rustc/src/platform-support/armv7-unknown-linux-uclibceabi.md b/src/doc/rustc/src/platform-support/armv7-unknown-linux-uclibceabi.md index e351ea0013003..f22a20835c1af 100644 --- a/src/doc/rustc/src/platform-support/armv7-unknown-linux-uclibceabi.md +++ b/src/doc/rustc/src/platform-support/armv7-unknown-linux-uclibceabi.md @@ -2,7 +2,7 @@ **Tier: 3** -This target supports ARMv7 softfloat CPUs and uses the uclibc-ng standard library. This is a common configuration on many consumer routers (e.g., Netgear R7000, Asus RT-AC68U). +This target supports Armv7-A softfloat CPUs and uses the uclibc-ng standard library. This is a common configuration on many consumer routers (e.g., Netgear R7000, Asus RT-AC68U). ## Target maintainers @@ -16,7 +16,7 @@ This target supports host tools and std. ## Building the target -You will need to download or build a `'C'` cross toolchain that targets ARMv7 softfloat and that uses the uclibc-ng standard library. If your target hardware is something like a router or an embedded device, keep in mind that manufacturer supplied SDKs for this class of CPU could be outdated and potentially unsuitable for bootstrapping rust. +You will need to download or build a `'C'` cross toolchain that targets Armv7-A softfloat and that uses the uclibc-ng standard library. If your target hardware is something like a router or an embedded device, keep in mind that manufacturer supplied SDKs for this class of CPU could be outdated and potentially unsuitable for bootstrapping rust. [Here](https://github.com/lancethepants/tomatoware-toolchain) is a sample toolchain that is built using [buildroot](https://buildroot.org/). It uses modern toolchain components, older thus universal kernel headers (2.6.36.4), and is used for a project called [Tomatoware](https://github.com/lancethepants/tomatoware). This toolchain is patched so that its sysroot is located at /mmc (e.g., /mmc/bin, /mmc/lib, /mmc/include). This is useful in scenarios where the root filesystem is read-only but you are able attach external storage loaded with user applications. Tomatoware is an example of this that even allows you to run various compilers and developer tools natively on the target device. @@ -46,7 +46,7 @@ The following assumes you are using the Tomatoware toolchain and environment. Ad ### Native compilation -Since this target supports host tools, you can natively build rust applications directly on your target device. This can be convenient because it removes the complexities of cross compiling and you can immediately test and deploy your binaries. One downside is that compiling on your ARMv7 CPU will probably be much slower than cross compilation on your x86 machine. +Since this target supports host tools, you can natively build rust applications directly on your target device. This can be convenient because it removes the complexities of cross compiling and you can immediately test and deploy your binaries. One downside is that compiling on your Armv7-A CPU will probably be much slower than cross compilation on your x86 machine. To setup native compilation: diff --git a/src/doc/rustc/src/platform-support/armv7-unknown-linux-uclibceabihf.md b/src/doc/rustc/src/platform-support/armv7-unknown-linux-uclibceabihf.md index 1f029406367a2..1c8acc09c7746 100644 --- a/src/doc/rustc/src/platform-support/armv7-unknown-linux-uclibceabihf.md +++ b/src/doc/rustc/src/platform-support/armv7-unknown-linux-uclibceabihf.md @@ -2,7 +2,7 @@ **Tier: 3** -This tier supports the ARMv7 processor running a Linux kernel and uClibc-ng standard library. It provides full support for rust and the rust standard library. +This tier supports the Armv7-A processor running a Linux kernel and uClibc-ng standard library. It provides full support for rust and the rust standard library. ## Designated Developers 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 670cead9e006b..5f0dc6a7115b9 100644 --- a/src/doc/rustc/src/platform-support/armv7r-none-eabi.md +++ b/src/doc/rustc/src/platform-support/armv7r-none-eabi.md @@ -2,7 +2,7 @@ **Tier: 2** -Bare-metal target for CPUs in the ARMv7-R architecture family, supporting +Bare-metal target for CPUs in the Armv7-R architecture family, supporting dual ARM/Thumb mode, with ARM mode as the default. Processors in this family include the [Arm Cortex-R4, 5, 7, and 8][cortex-r]. diff --git a/src/doc/rustc/src/platform-support/armv8r-none-eabihf.md b/src/doc/rustc/src/platform-support/armv8r-none-eabihf.md index 588e5d7c99449..6f80a06020ff7 100644 --- a/src/doc/rustc/src/platform-support/armv8r-none-eabihf.md +++ b/src/doc/rustc/src/platform-support/armv8r-none-eabihf.md @@ -2,7 +2,7 @@ **Tier: 3** -Bare-metal target for CPUs in the ARMv8-R architecture family, supporting +Bare-metal target for CPUs in the Armv8-R architecture family, supporting dual ARM/Thumb mode, with ARM mode as the default. Processors in this family include the Arm [Cortex-R52][cortex-r52] 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 32f2a573973fb..f4ed6201bbdc9 100644 --- a/src/doc/rustc/src/platform-support/thumbv6m-none-eabi.md +++ b/src/doc/rustc/src/platform-support/thumbv6m-none-eabi.md @@ -2,7 +2,7 @@ **Tier: 2** -Bare-metal target for CPUs in the [ARMv6-M] architecture family, supporting a +Bare-metal target for CPUs in the [Armv6-M] architecture family, supporting a subset of the [T32 ISA][t32-isa]. Processors in this family include the: @@ -16,10 +16,10 @@ See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all This target uses the soft-float ABI: functions which take `f32` or `f64` as arguments will have those values packed into integer registers. This is the -only option because there is no FPU support in [ARMv6-M]. +only option because there is no FPU support in [Armv6-M]. [t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture -[ARMv6-M]: https://developer.arm.com/documentation/ddi0419/latest/ +[Armv6-M]: https://developer.arm.com/documentation/ddi0419/latest/ [cortex-m0]: https://developer.arm.com/Processors/Cortex-M0 [cortex-m0plus]: https://developer.arm.com/Processors/Cortex-M0+ [cortex-m1]: https://developer.arm.com/Processors/Cortex-M1 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 698c8ae7a6551..f25ef0383b185 100644 --- a/src/doc/rustc/src/platform-support/thumbv7em-none-eabi.md +++ b/src/doc/rustc/src/platform-support/thumbv7em-none-eabi.md @@ -2,7 +2,7 @@ **Tier: 2** -Bare-metal target for CPUs in the [ARMv7E-M] architecture family, supporting a +Bare-metal target for CPUs in the [Armv7E-M] architecture family, supporting a subset of the [T32 ISA][t32-isa]. Processors in this family include the: @@ -15,7 +15,7 @@ See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all `eabihf` ABI. [t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture -[ARMv7E-M]: https://developer.arm.com/documentation/ddi0403/latest/ +[Armv7E-M]: https://developer.arm.com/documentation/ddi0403/latest/ [cortex-m4]: https://developer.arm.com/Processors/Cortex-M4 [cortex-m7]: https://developer.arm.com/Processors/Cortex-M7 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 793e0d7d2de90..b258033bb0fa7 100644 --- a/src/doc/rustc/src/platform-support/thumbv7m-none-eabi.md +++ b/src/doc/rustc/src/platform-support/thumbv7m-none-eabi.md @@ -2,7 +2,7 @@ **Tier: 2** -Bare-metal target for CPUs in the [ARMv7-M] architecture family, supporting a +Bare-metal target for CPUs in the [Armv7-M] architecture family, supporting a subset of the [T32 ISA][t32-isa]. Processors in this family include the: @@ -14,10 +14,10 @@ See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all This target uses the soft-float ABI: functions which take `f32` or `f64` as arguments will have those values packed into integer registers. This is the -only option because there is no FPU support in [ARMv7-M]. +only option because there is no FPU support in [Armv7-M]. [t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture -[ARMv7-M]: https://developer.arm.com/documentation/ddi0403/latest/ +[Armv7-M]: https://developer.arm.com/documentation/ddi0403/latest/ [cortex-m3]: https://developer.arm.com/Processors/Cortex-M3 ## Target maintainers 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 c63620067acfd..0ae4e3e94bd8c 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 @@ -2,7 +2,7 @@ **Tier: 2** -Bare-metal target for CPUs in the Baseline [ARMv8-M] architecture family, +Bare-metal target for CPUs in the Baseline [Armv8-M] architecture family, supporting a subset of the [T32 ISA][t32-isa]. Processors in this family include the: @@ -14,10 +14,10 @@ See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all This target uses the soft-float ABI: functions which take `f32` or `f64` as arguments will have those values packed into integer registers. This is the -only option because there is no FPU support in [ARMv8-M] Baseline. +only option because there is no FPU support in [Armv8-M] Baseline. [t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture -[ARMv8-M]: https://developer.arm.com/documentation/ddi0553/latest/ +[Armv8-M]: https://developer.arm.com/documentation/ddi0553/latest/ [cortex-m23]: https://developer.arm.com/Processors/Cortex-M23 ## Target maintainers 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 9541e1d582c23..4e696f9c30461 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 @@ -2,7 +2,7 @@ **Tier: 2** -Bare-metal target for CPUs in the Mainline [ARMv8-M] architecture family, +Bare-metal target for CPUs in the Mainline [Armv8-M] architecture family, supporting a subset of the [T32 ISA][t32-isa]. Processors in this family include the: @@ -17,7 +17,7 @@ See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all `eabihf` ABI. [t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture -[ARMv8-M]: https://developer.arm.com/documentation/ddi0553/latest/ +[Armv8-M]: https://developer.arm.com/documentation/ddi0553/latest/ [cortex-m33]: https://developer.arm.com/Processors/Cortex-M33 [cortex-m35p]: https://developer.arm.com/Processors/Cortex-M35P [cortex-m55]: https://developer.arm.com/Processors/Cortex-M55 From fcaba9ce5c94b07c2394e61d65711c14bb33d6cb Mon Sep 17 00:00:00 2001 From: Jonathan Pallant Date: Tue, 30 Apr 2024 10:00:19 +0100 Subject: [PATCH 8/8] arm target docs: clarify A32/T32/Arm ISA/Thumb ISA/Thumb-2 ISA --- .../src/platform-support/arm-none-eabi.md | 51 +++++++++++++------ 1 file changed, 36 insertions(+), 15 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 4560860b88baf..0b1b10e4762e7 100644 --- a/src/doc/rustc/src/platform-support/arm-none-eabi.md +++ b/src/doc/rustc/src/platform-support/arm-none-eabi.md @@ -34,21 +34,43 @@ 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 +There are two 32-bit instruction set architectures (ISAs) defined by Arm: + +- The [*A32 ISA*][a32-isa], with fixed-width 32-bit instructions. Previously + known as the *Arm* ISA, this originated with the original ARM1 of 1985 and has + been updated by various revisions to the architecture specifications ever + since. +- The [*T32 ISA*][t32-isa], with a mix of 16-bit and 32-bit width instructions. + Note that this term includes both the original 16-bit width *Thumb* ISA + introduced with the Armv4T architecture in 1994, and the later 16/32-bit sized + *Thumb-2* ISA introduced with the Armv6T2 architecture in 2003. Again, these + ISAs have been revised by subsequent revisions to the relevant Arm + architecture specifications. + +There is also a 64-bit ISA with fixed-width 32-bit instructions called the *A64 +ISA*, but targets which implement that instruction set generally start with +`aarch64*` and are discussed elsewhere. + +Rust targets starting with `arm*` generate Arm (A32) code by default, whilst +targets named `thumb*` generate Thumb (T32) code by default. Most Arm chips +support both Thumb mode and Arm mode, with the notable exception that M-profile +processors (`thumbv*m*-none-eabi*` targets) *only* support Thumb-mode. + +Rust targets ending with `eabi` use 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 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 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 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. For example, if a given hard-float -target has baseline *single-precision* (`f32`) support in hardware, there may be +Rust targets ending in `eabihf` use 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 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. 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. @@ -59,6 +81,9 @@ processor cannot support will be lowered to library calls (like `__aeabi_dadd`) which perform the floating-point operation in software using integer instructions. +[t32-isa]: https://developer.arm.com/Architectures/T32%20Instruction%20Set%20Architecture +[a32-isa]: https://developer.arm.com/Architectures/A32%20Instruction%20Set%20Architecture + ## Target CPU and Target Feature options It is possible to tell Rust (or LLVM) that you have a specific model of Arm @@ -126,10 +151,6 @@ according to the specific device you are using. Pass `-Clink-arg=-Tyour_script.ld` as a rustc argument to make the linker use `your_script.ld` during linking. -Targets named `thumb*` instead of `arm*` generate Thumb (T32) code by default -instead of Arm (A32) code. Most Arm chips support both Thumb mode and Arm mode, -except that M-profile processors (`thumbv*m*-*` targets) only support Thumb-mode. - For the `arm*` targets, Thumb-mode code generation can be enabled by using `-C target-feature=+thumb-mode`. Using the unstable `#![feature(arm_target_feature)]`, the attribute `#[target_feature(enable =