doc/rustc: fill out target platform-support docs

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.

src/doc/rustc/src/platform-support/riscv32i_unknown_none_elf.md

@@ -0,0 +1 @@
+riscv32imac_unknown_none_elf.md

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.

src/doc/rustc/src/platform-support/riscv32imc_unknown_none_elf.md

@@ -0,0 +1 @@
+riscv32imac_unknown_none_elf.md

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`.

src/doc/rustc/src/platform-support/thumbv7em_none_eabi.md

@@ -1 +1 @@
-./thumbv7m_none_eabi.md
+thumbv7m_none_eabi.md

src/doc/rustc/src/platform-support/thumbv7em_none_eabihf.md

@@ -0,0 +1 @@
+thumbv7m_none_eabi.md

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.

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.