Arm bare-metal target doc changes

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])

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 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
+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 disassemble the compiler output and manually inspect
+it to ensure only appropriate instructions for your CPU have been generated.
+
+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):
+
+```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.

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), `[email protected]`
+
+## 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.

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), `[email protected]`
+
+## 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

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), `[email protected]`
+
+## 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*