From 7cfb29878a24928ee47e48ab96baca6a9b43ba1d Mon Sep 17 00:00:00 2001
From: Adam Greig <adam@adamgreig.com>
Date: Mon, 9 Oct 2023 00:47:04 +0100
Subject: [PATCH] doc/rustc: fill out target platform-support docs
Adds maintainers and other information for bare-metal MSP430, RISC-V
RV32I/IMC/IMAC, and thumbv{6,7,8} targets.
Signed-off-by: Adam Greig <adam@adamgreig.com>
---
.../src/platform-support/msp430_none_elf.md | 33 +++++++---
.../riscv32i_unknown_none_elf.md | 30 +--------
.../riscv32imac_unknown_none_elf.md | 27 ++++----
.../riscv32imc_unknown_none_elf.md | 30 +--------
.../platform-support/thumbv6m_none_eabi.md | 33 +++++++---
.../platform-support/thumbv7em_none_eabi.md | 2 +-
.../platform-support/thumbv7em_none_eabihf.md | 34 +---------
.../platform-support/thumbv7m_none_eabi.md | 63 ++++++++++++++++++-
.../thumbv8m_base_none_eabi.md | 40 +++++++++---
.../thumbv8m_main_none_eabi.md | 30 +--------
.../thumbv8m_main_none_eabihf.md | 2 +-
11 files changed, 163 insertions(+), 161 deletions(-)
mode change 100644 => 120000 src/doc/rustc/src/platform-support/riscv32i_unknown_none_elf.md
mode change 100644 => 120000 src/doc/rustc/src/platform-support/riscv32imc_unknown_none_elf.md
mode change 100644 => 120000 src/doc/rustc/src/platform-support/thumbv7em_none_eabihf.md
mode change 120000 => 100644 src/doc/rustc/src/platform-support/thumbv7m_none_eabi.md
mode change 100644 => 120000 src/doc/rustc/src/platform-support/thumbv8m_main_none_eabi.md
diff --git a/src/doc/rustc/src/platform-support/msp430_none_elf.md b/src/doc/rustc/src/platform-support/msp430_none_elf.md
index ffe549ae00612..c54432adb24bb 100644
--- a/src/doc/rustc/src/platform-support/msp430_none_elf.md
+++ b/src/doc/rustc/src/platform-support/msp430_none_elf.md
@@ -6,24 +6,41 @@
## Target maintainers
-- Missing!
+* Rust Embedded Working Group, [MSP430 team](https://github.com/rust-embedded/wg#the-msp430-team)
## Requirements
-Missing!
+TI's [MSP430 GCC compiler], version 8.3.0 or greater, must be installed, with
+`msp430-elf-gcc` visible on your path. You must specify a linker script; the
+[`msp430-rt`] crate provides a suitable one. Refer to [`msp430-quickstart`]
+for detailed instructions.
-## Building the target
+A nightly Rust is required for the forseeable future until at least [#3246]
+and [#38487] are resolved.
+
+[MSP430 GCC compiler]: http://www.ti.com/tool/MSP430-GCC-OPENSOURCE
+[`msp430-rt`]: https://github.com/rust-embedded/msp430-rt
+[`msp430-quickstart`]: https://github.com/rust-embedded/msp430-quickstart
+[#3246]: https://github.com/rust-lang/rfcs/pull/3246
+[#38487]: https://github.com/rust-lang/rust/issues/38487
-Missing!
+## Building the target
-## Building Rust programs
+Rust does not ship pre-built versions of libcore for this target. Using a
+nightly Cargo version, add the following to your `.cargo/config.toml` file:
-Missing!
+```toml
+[unstable]
+build-std = ["core"]
+```
## Testing
-Missing!
+This is a cross-compiled no-std target, which must be run either in a simulator
+or by programming them onto suitable hardware. It is not possible to run the
+Rust testsuite on this target.
## Cross-compilation toolchains and C code
-Missing!
+This target supports interlinking with C code compiled using the TI MSP430 GCC
+compiler, but cross-language LTO is not supported.
diff --git a/src/doc/rustc/src/platform-support/riscv32i_unknown_none_elf.md b/src/doc/rustc/src/platform-support/riscv32i_unknown_none_elf.md
deleted file mode 100644
index 2c96c3ac5c7a1..0000000000000
--- a/src/doc/rustc/src/platform-support/riscv32i_unknown_none_elf.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# `riscv32i-unknown-none-elf`
-
-**Tier: 2**
-
-Bare RISC-V (RV32I ISA)
-
-## Target maintainers
-
-- Missing!
-
-## Requirements
-
-Missing!
-
-## Building the target
-
-Missing!
-
-## Building Rust programs
-
-Missing!
-
-## Testing
-
-Missing!
-
-## Cross-compilation toolchains and C code
-
-Missing!
diff --git a/src/doc/rustc/src/platform-support/riscv32i_unknown_none_elf.md b/src/doc/rustc/src/platform-support/riscv32i_unknown_none_elf.md
new file mode 120000
index 0000000000000..bcbfd59415114
--- /dev/null
+++ b/src/doc/rustc/src/platform-support/riscv32i_unknown_none_elf.md
@@ -0,0 +1 @@
+riscv32imac_unknown_none_elf.md
\ No newline at end of file
diff --git a/src/doc/rustc/src/platform-support/riscv32imac_unknown_none_elf.md b/src/doc/rustc/src/platform-support/riscv32imac_unknown_none_elf.md
index beff28ad8b135..3122dd6bed706 100644
--- a/src/doc/rustc/src/platform-support/riscv32imac_unknown_none_elf.md
+++ b/src/doc/rustc/src/platform-support/riscv32imac_unknown_none_elf.md
@@ -1,29 +1,34 @@
-# `riscv32imac-unknown-none-elf`
+# `riscv32{i,imc,imac}-unknown-none-elf`
**Tier: 2**
-Bare RISC-V (RV32IMAC ISA)
+Bare-metal target for RISC-V CPUs with the RV32I, RV32IMC, and RV32IMAC ISAs.
## Target maintainers
-- Missing!
+* Rust Embedded Working Group, [RISC-V team](https://github.com/rust-embedded/wg#the-risc-v-team)
## Requirements
-Missing!
+The target is cross-compiled, and uses static linking. No external toolchain
+is required and the default `rust-lld` linker works, but you must specify
+a linker script. The [`riscv-rt`] crate provides a suitable one. The
+[`riscv-rust-quickstart`] repository gives an example of an RV32 project.
-## Building the target
-
-Missing!
+[`riscv-rt`]: https://crates.io/crates/riscv-rt
+[`riscv-rust-quickstart`]: https://github.com/riscv-rust/riscv-rust-quickstart
-## Building Rust programs
+## Building the target
-Missing!
+This target is included in Rust and can be installed via `rustup`.
## Testing
-Missing!
+This is a cross-compiled no-std target, which must be run either in a simulator
+or by programming them onto suitable hardware. It is not possible to run the
+Rust testsuite on this target.
## Cross-compilation toolchains and C code
-Missing!
+This target supports C code. If interlinking with C or C++, you may need to use
+riscv64-unknown-elf-gcc as a linker instead of rust-lld.
diff --git a/src/doc/rustc/src/platform-support/riscv32imc_unknown_none_elf.md b/src/doc/rustc/src/platform-support/riscv32imc_unknown_none_elf.md
deleted file mode 100644
index a0c1be8f27e50..0000000000000
--- a/src/doc/rustc/src/platform-support/riscv32imc_unknown_none_elf.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# `riscv32imc-unknown-none-elf`
-
-**Tier: 2**
-
-Bare RISC-V (RV32IMC ISA)
-
-## Target maintainers
-
-- Missing!
-
-## Requirements
-
-Missing!
-
-## Building the target
-
-Missing!
-
-## Building Rust programs
-
-Missing!
-
-## Testing
-
-Missing!
-
-## Cross-compilation toolchains and C code
-
-Missing!
diff --git a/src/doc/rustc/src/platform-support/riscv32imc_unknown_none_elf.md b/src/doc/rustc/src/platform-support/riscv32imc_unknown_none_elf.md
new file mode 120000
index 0000000000000..bcbfd59415114
--- /dev/null
+++ b/src/doc/rustc/src/platform-support/riscv32imc_unknown_none_elf.md
@@ -0,0 +1 @@
+riscv32imac_unknown_none_elf.md
\ No newline at end of file
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 ef66b68ecc26c..c81f1df32274e 100644
--- a/src/doc/rustc/src/platform-support/thumbv6m_none_eabi.md
+++ b/src/doc/rustc/src/platform-support/thumbv6m_none_eabi.md
@@ -2,28 +2,43 @@
**Tier: 2**
-Bare ARMv6-M
+Bare-metal target for ARMv6-M CPUs, including Cortex-M0, Cortex-M0+, and
+Cortex-M1.
## Target maintainers
-- Missing!
+* Rust Embedded Working Group, [Cortex-M team](https://github.com/rust-embedded/wg#the-cortex-m-team)
## Requirements
-Missing!
+The target is cross-compiled, and uses static linking. No external toolchain
+is required and the default `rust-lld` linker works, but you must specify
+a linker script. The [`cortex-m-rt`] crate provides a suitable one. The
+[`cortex-m-quickstart`] repository gives an example of a Cortex-M project.
-## Building the target
+[`cortex-m-rt`]: https://crates.io/crates/cortex-m-rt
+[`cortex-m-quickstart`]: https://github.com/rust-embedded/cortex-m-quickstart
+
+## Atomics
-Missing!
+Rust enables 32-bit atomics with only load and store operations. There is no
+hardware support for compare-and-swap. These atomics are ABI incompatible with
+atomics backed by libatomic in C or C++. You may find the [portable-atomic]
+crate useful to provide atomic compare-and-set operations.
-## Building Rust programs
+[portable-atomic]: https://crates.io/crates/portable-atomic
+
+## Building the target
-Missing!
+This target is included in Rust and can be installed via `rustup`.
## Testing
-Missing!
+This is a cross-compiled no-std target, which must be run either in a simulator
+or by programming them onto suitable hardware. It is not possible to run the
+Rust testsuite on this target.
## Cross-compilation toolchains and C code
-Missing!
+This target supports C code. If interlinking with C or C++, you may need to
+use `arm-none-eabi-gcc` as a linker instead of `rust-lld`.
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 2e8f7042cfdf5..edd3812fb3bf0 120000
--- a/src/doc/rustc/src/platform-support/thumbv7em_none_eabi.md
+++ b/src/doc/rustc/src/platform-support/thumbv7em_none_eabi.md
@@ -1 +1 @@
-./thumbv7m_none_eabi.md
\ No newline at end of file
+thumbv7m_none_eabi.md
\ No newline at end of file
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 918cb3cdccde9..0000000000000
--- a/src/doc/rustc/src/platform-support/thumbv7em_none_eabihf.md
+++ /dev/null
@@ -1,33 +0,0 @@
-# `thumbv7{m,em}-none-eabi{,hf}`
-
-**Tier: 2**
-
-| Target | Description |
-| ======================= | ======================== |
-| `thumbv7em-none-eabi` | Bare ARMv7E-M |
-| `thumbv7em-none-eabihf` | Bare ARMv7E-M, hardfloat |
-| `thumbv7m-none-eabi` | Bare ARMv7-M |
-
-## Target maintainers
-
-- Missing!
-
-## Requirements
-
-Missing!
-
-## Building the target
-
-Missing!
-
-## Building Rust programs
-
-Missing!
-
-## Testing
-
-Missing!
-
-## Cross-compilation toolchains and C code
-
-Missing!
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 120000
index 0000000000000..edd3812fb3bf0
--- /dev/null
+++ b/src/doc/rustc/src/platform-support/thumbv7em_none_eabihf.md
@@ -0,0 +1 @@
+thumbv7m_none_eabi.md
\ No newline at end of file
diff --git a/src/doc/rustc/src/platform-support/thumbv7m_none_eabi.md b/src/doc/rustc/src/platform-support/thumbv7m_none_eabi.md
deleted file mode 120000
index 772d6274307b0..0000000000000
--- a/src/doc/rustc/src/platform-support/thumbv7m_none_eabi.md
+++ /dev/null
@@ -1 +0,0 @@
-./thumbv7em_none_eabihf.md
\ No newline at end of file
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..d7e1dd6421242
--- /dev/null
+++ b/src/doc/rustc/src/platform-support/thumbv7m_none_eabi.md
@@ -0,0 +1,62 @@
+# `thumbv7{m,em}-none-eabi{,hf}`
+
+**Tier: 2**
+
+Bare-metal targets for ARMv7-M CPUs, including Cortex-M3, Cortex-M4, and
+Cortex-M7. Three targets are available, depending on the use of the `E` DSP
+extension (Cortex-M4 and Cortex-M7 only) and the presence of a hardware
+floating-point unit.
+
+| Target | Description |
+|-------------------------|--------------------------|
+| `thumbv7em-none-eabi` | Bare ARMv7E-M |
+| `thumbv7em-none-eabihf` | Bare ARMv7E-M, hardfloat |
+| `thumbv7m-none-eabi` | Bare ARMv7-M |
+
+## Target maintainers
+
+* Rust Embedded Working Group, [Cortex-M team](https://github.com/rust-embedded/wg#the-cortex-m-team)
+
+## Requirements
+
+The target is cross-compiled, and uses static linking. No external toolchain
+is required and the default `rust-lld` linker works, but you must specify
+a linker script. The [`cortex-m-rt`] crate provides a suitable one. The
+[`cortex-m-quickstart`] repository gives an example of a Cortex-M project.
+
+[`cortex-m-rt`]: https://crates.io/crates/cortex-m-rt
+[`cortex-m-quickstart`]: https://github.com/rust-embedded/cortex-m-quickstart
+
+## Floating-point
+
+The `thumbv7em-none-eabihf` target assumes that the device has a hardware FPU
+and lowers all floating point operations to hardware instructions.
+Additionally, this target uses the "hard" float ABI, where floating
+point values are passed to/from subroutines via FPU registers.
+
+To opt in to double precision hardware FPU support on Cortex-M7,
+use the `-C target-feature=+fp64` or `-C target-cpu=cortex-m7` flags.
+
+It is also possible to use the hardware FPU while using the soft float ABI, by
+using the `thumbv7em-none-eabi` target and passing `-C target-cpu=cortex-m4`
+(or `cortex-m7`). In this case the FPU must be enabled at startup, before
+entering any function which takes floating-point arguments or uses any
+floating-point variables. The [`cortex-m`] crate provides the
+`SCB::enable_fpu()` convenience function to enable the FPU.
+
+[`cortex-m`]: https://crates.io/crates/cortex-m
+
+## Building the target
+
+This target is included in Rust and can be installed via `rustup`.
+
+## Testing
+
+This is a cross-compiled no-std target, which must be run either in a simulator
+or by programming them onto suitable hardware. It is not possible to run the
+Rust testsuite on this target.
+
+## Cross-compilation toolchains and C code
+
+This target supports C code. If interlinking with C or C++, you may need to
+use `arm-none-eabi-gcc` as a linker instead of the built-in LLD.
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 45ca4f546d5ed..9917daaf5e6ef 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
@@ -1,29 +1,49 @@
-# `thumbv8m.base-none-eabi`
+# `thumbv8m.{base,main}-none-eabi{,hf}`
**Tier: 2**
-Bare ARMv8-M Baseline
+Bare-metal target for ARMv8-M baseline and mainline CPUs, including Cortex-M23,
+Cortex-M33, M35P, M55, and M85. The `-eabihf` target enables the hardware FPU
+and uses the hard-float ABI.
+
+| Target | Description |
+|-----------------------------|--------------------------------------|
+| `thumbv8m.base-none-eabi` | Bare ARMv8-M baseline |
+| `thumbv8m.main-none-eabi` | Bare ARMv8-M mainline |
+| `thumbv8m.main-none-eabihf` | Bare ARMv8-M mainline with hardfloat |
## Target maintainers
-- Missing!
+* Rust Embedded Working Group, [Cortex-M team](https://github.com/rust-embedded/wg#the-cortex-m-team)
## Requirements
-Missing!
+The target is cross-compiled, and uses static linking. No external toolchain
+is required and the default `rust-lld` linker works, but you must specify
+a linker script. The [`cortex-m-rt`] crate provides a suitable one. The
+[`cortex-m-quickstart`] repository gives an example of a Cortex-M project.
-## Building the target
+[`cortex-m-rt`]: https://crates.io/crates/cortex-m-rt
+[`cortex-m-quickstart`]: https://github.com/rust-embedded/cortex-m-quickstart
-Missing!
+## Floating-point
-## Building Rust programs
+The `thumbv8m.main-none-eabihf` target assumes that the device has a hardware
+FPU and lowers all floating point operations to hardware instructions.
+Additionally, this target uses the "hard" float ABI, where floating point
+values are passed to/from subroutines via FPU registers.
+
+## Building the target
-Missing!
+This target is included in Rust and can be installed via `rustup`.
## Testing
-Missing!
+This is a cross-compiled no-std target, which must be run either in a simulator
+or by programming them onto suitable hardware. It is not possible to run the
+Rust testsuite on this target.
## Cross-compilation toolchains and C code
-Missing!
+This target supports C code. If interlinking with C or C++, you may need to
+use `arm-none-eabi-gcc` as a linker instead of the built-in LLD.
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
deleted file mode 100644
index 2a7ecad865495..0000000000000
--- a/src/doc/rustc/src/platform-support/thumbv8m_main_none_eabi.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# `thumbv8m.main-none-eabi{,hf}`
-
-**Tier: 2**
-
-Bare ARMv8-M Mainline (with and without hardfloat)
-
-## Target maintainers
-
-- Missing!
-
-## Requirements
-
-Missing!
-
-## Building the target
-
-Missing!
-
-## Building Rust programs
-
-Missing!
-
-## Testing
-
-Missing!
-
-## Cross-compilation toolchains and C code
-
-Missing!
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 120000
index 0000000000000..38a472f04a103
--- /dev/null
+++ b/src/doc/rustc/src/platform-support/thumbv8m_main_none_eabi.md
@@ -0,0 +1 @@
+thumbv8m_base_none_eabi.md
\ No newline at end of file
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
index df76184adad84..38a472f04a103 120000
--- a/src/doc/rustc/src/platform-support/thumbv8m_main_none_eabihf.md
+++ b/src/doc/rustc/src/platform-support/thumbv8m_main_none_eabihf.md
@@ -1 +1 @@
-./thumbv8m_main_none_eabi.md
\ No newline at end of file
+thumbv8m_base_none_eabi.md
\ No newline at end of file