Add pages for every Cortex-M target

Now explains how to, for example, support a Cortex-M55 with FPU and Integer Helium.

9 files changed, 646 insertions, 39 deletions

diff --git a/src/doc/rustc/src/platform-support.md b/src/doc/rustc/src/platform-support.md
index 2578b71a158..526b5a59789 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 6335a6405a1..de41c5e676a 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 00000000000..f75194c815e
--- /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 00000000000..632f1681bb9
--- /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 00000000000..d4c93e3197c
--- /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 00000000000..2c10f679f66
--- /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 00000000000..6e9d2329aa9
--- /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 00000000000..eca9a7b1a70
--- /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 00000000000..8f353a8d3db
--- /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)