From 90893e4850f463618bd06ae6d3e30f0075559e24 Mon Sep 17 00:00:00 2001 From: Chris Copeland Date: Sun, 13 Aug 2023 03:51:03 -0700 Subject: [PATCH] Add arm-none-eabi and armv7r-none-eabi platform-support documentation. --- src/doc/rustc/src/SUMMARY.md | 2 + src/doc/rustc/src/platform-support.md | 42 ++++---- .../src/platform-support/arm-none-eabi.md | 96 +++++++++++++++++++ .../src/platform-support/armv4t-none-eabi.md | 45 +-------- .../src/platform-support/armv5te-none-eabi.md | 50 +--------- .../src/platform-support/armv7r-none-eabi.md | 47 +++++++++ 6 files changed, 176 insertions(+), 106 deletions(-) create mode 100644 src/doc/rustc/src/platform-support/arm-none-eabi.md create mode 100644 src/doc/rustc/src/platform-support/armv7r-none-eabi.md diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md index f46daca1f3075..fadd64a0353cb 100644 --- a/src/doc/rustc/src/SUMMARY.md +++ b/src/doc/rustc/src/SUMMARY.md @@ -22,8 +22,10 @@ - [\*-apple-watchos\*](platform-support/apple-watchos.md) - [aarch64-nintendo-switch-freestanding](platform-support/aarch64-nintendo-switch-freestanding.md) - [armeb-unknown-linux-gnueabi](platform-support/armeb-unknown-linux-gnueabi.md) + - [arm-none-eabi](platform-support/arm-none-eabi.md) - [armv4t-none-eabi](platform-support/armv4t-none-eabi.md) - [armv5te-none-eabi](platform-support/armv5te-none-eabi.md) + - [armv7r-none-eabi](platform-support/armv7r-none-eabi.md) - [armv6k-nintendo-3ds](platform-support/armv6k-nintendo-3ds.md) - [armv7-sony-vita-newlibeabihf](platform-support/armv7-sony-vita-newlibeabihf.md) - [armv7-unknown-linux-uclibceabi](platform-support/armv7-unknown-linux-uclibceabi.md) diff --git a/src/doc/rustc/src/platform-support.md b/src/doc/rustc/src/platform-support.md index 5535e69c86acd..a1d2281ca4884 100644 --- a/src/doc/rustc/src/platform-support.md +++ b/src/doc/rustc/src/platform-support.md @@ -137,17 +137,17 @@ target | std | notes [`arm-linux-androideabi`](platform-support/android.md) | ✓ | ARMv6 Android `arm-unknown-linux-musleabi` | ✓ | ARMv6 Linux with MUSL `arm-unknown-linux-musleabihf` | ✓ | ARMv6 Linux with MUSL, hardfloat -`armebv7r-none-eabi` | * | Bare ARMv7-R, Big Endian -`armebv7r-none-eabihf` | * | Bare ARMv7-R, Big Endian, 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 [`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 `armv7-unknown-linux-musleabihf` | ✓ | ARMv7-A Linux with MUSL, hardfloat -`armv7a-none-eabi` | * | Bare ARMv7-A -`armv7r-none-eabi` | * | Bare ARMv7-R -`armv7r-none-eabihf` | * | Bare ARMv7-R, hardfloat +[`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 [^x86_32-floats-x87] @@ -166,15 +166,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` | * | Bare ARMv6-M -`thumbv7em-none-eabi` | * | Bare ARMv7E-M -`thumbv7em-none-eabihf` | * | Bare ARMV7E-M, hardfloat -`thumbv7m-none-eabi` | * | Bare ARMv7-M +[`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 [`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` | * | Bare ARMv8-M Baseline -`thumbv8m.main-none-eabi` | * | Bare ARMv8-M Mainline -`thumbv8m.main-none-eabihf` | * | Bare ARMv8-M Mainline, hardfloat +[`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 `wasm32-unknown-emscripten` | ✓ | WebAssembly via Emscripten `wasm32-unknown-unknown` | ✓ | WebAssembly `wasm32-wasi` | ✓ | WebAssembly with WASI @@ -238,11 +238,11 @@ 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 +[`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` | * | | Bare ARMv4T +[`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-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 @@ -256,8 +256,8 @@ target | std | host | notes `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` | * | | Bare ARMv7-A, hardfloat -[`armv7k-apple-watchos`](platform-support/apple-watchos.md) | ✓ | | ARMv7-A Apple WatchOS +[`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 `avr-unknown-gnu-atmega328` | * | | AVR. Requires `-Z build-std=core` `bpfeb-unknown-none` | * | | BPF (big endian) @@ -332,15 +332,15 @@ 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` | * | | 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 [`wasm64-unknown-unknown`](platform-support/wasm64-unknown-unknown.md) | ? | | WebAssembly `x86_64-apple-ios-macabi` | ✓ | | Apple Catalyst on x86_64 -[`x86_64-apple-tvos`](platform-support/apple-tvos.md) | ? | | x86 64-bit tvOS -[`x86_64-apple-watchos-sim`](platform-support/apple-watchos.md) | ✓ | | x86 64-bit Apple WatchOS simulator +[`x86_64-apple-tvos`](platform-support/apple-tvos.md) | ? | | x86 64-bit tvOS +[`x86_64-apple-watchos-sim`](platform-support/apple-watchos.md) | ✓ | | x86 64-bit Apple WatchOS simulator [`x86_64-pc-nto-qnx710`](platform-support/nto-qnx.md) | ✓ | | x86 64-bit QNX Neutrino 7.1 RTOS | [`x86_64-pc-windows-gnullvm`](platform-support/pc-windows-gnullvm.md) | ✓ | ✓ | `x86_64-pc-windows-msvc` | * | | 64-bit Windows XP support diff --git a/src/doc/rustc/src/platform-support/arm-none-eabi.md b/src/doc/rustc/src/platform-support/arm-none-eabi.md new file mode 100644 index 0000000000000..4f76d0d7bbce7 --- /dev/null +++ b/src/doc/rustc/src/platform-support/arm-none-eabi.md @@ -0,0 +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 + +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. + +## Requirements + +These targets are cross-compiled and use static linking. + +By default, the `lld` linker included with Rust will be used; however, you may +want to use the GNU linker instead. This can be obtained for Windows/Mac/Linux +from the [Arm Developer Website][arm-gnu-toolchain], or possibly from your OS's +package manager. To use it, add the following to your `.cargo/config.toml`: + +```toml +[target.] +linker = "arm-none-eabi-ld" +``` + +The GNU linker can also be used by specifying `arm-none-eabi-gcc` as the +linker. This is needed when using GCC's link time optimization. + +[arm-gnu-toolchain]: https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain + +These targets don't provide a linker script, so you'll need to bring your own +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. + +## Building Rust Programs + +For the Tier 3 targets in this family, rust does not ship pre-compiled +artifacts. + +Just use the `build-std` nightly cargo feature to build the `core` library. You +can pass this as a command line argument to cargo, or your `.cargo/config.toml` +file might include the following lines: + +```toml +[unstable] +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. +* Integer division is also emulated in software on some targets, depending on + the CPU. +* Architectures prior to ARMv7 don't have atomic instructions. + +`alloc` is also supported, as long as you provide your own global allocator. + +Rust programs are output as ELF files. + +## Testing + +This is a cross-compiled target that you will need to emulate during testing. + +The exact emulator that you'll need depends on the specific device you want to +run your code on. + +## Cross-compilation toolchains and C code + +The target supports C code compiled with the `arm-none-eabi` target triple and +a suitable `-march` or `-mcpu` flag. + +`gcc` or `clang` can be used, but note that `gcc` uses `-fshort-enums` by +default for `arm-none*` targets, while `clang` does not. `rustc` matches the +`gcc` behavior, i.e., the size of a `#[repr(C)] enum` in Rust can be as little +as 1 byte, rather than 4, as they are on `arm-linux` targets. 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 a230eba6bf95c..29c47db8351c7 100644 --- a/src/doc/rustc/src/platform-support/armv4t-none-eabi.md +++ b/src/doc/rustc/src/platform-support/armv4t-none-eabi.md @@ -6,51 +6,16 @@ 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 Gameboy Advance (GBA), but there's nothing GBA -specific with this target, so any ARMv4T device should work fine. +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. + +See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all +`arm-none-eabi` targets. ## Target Maintainers * [@Lokathor](https://github.com/lokathor) -## Requirements - -The target is cross-compiled, and uses static linking. - -This target doesn't provide a linker script, you'll need to bring your own -according to the specific device you want to target. Pass -`-Clink-arg=-Tyour_script.ld` as a rustc argument to make the linker use -`your_script.ld` during linking. - -## Building Rust Programs - -Because it is Tier 3, rust does not yet ship pre-compiled artifacts for this target. - -Just use the `build-std` nightly cargo feature to build the `core` library. You -can pass this as a command line argument to cargo, or your `.cargo/config.toml` -file might include the following lines: - -```toml -[unstable] -build-std = ["core"] -``` - -Most of `core` should work as expected, with the following notes: -* the target is "soft float", so `f32` and `f64` operations are emulated in - software. -* integer division is also emulated in software. -* the target is old enough that it doesn't have atomic instructions. - -Rust programs are output as ELF files. - -For running on hardware, you'll generally need to extract the "raw" program code -out of the ELF and into a file of its own. The `objcopy` program provided as -part of the GNU Binutils can do this: - -```shell -arm-none-eabi-objcopy --output-target binary [in_file] [out_file] -``` - ## Testing This is a cross-compiled target that you will need to emulate during testing. 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 f469dab1c42fa..37284ba720997 100644 --- a/src/doc/rustc/src/platform-support/armv5te-none-eabi.md +++ b/src/doc/rustc/src/platform-support/armv5te-none-eabi.md @@ -8,54 +8,13 @@ generation. 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. + ## Target Maintainers * [@QuinnPainter](https://github.com/QuinnPainter) -## Requirements - -The target is cross-compiled, and uses static linking. - -By default, the `lld` linker included with Rust will be used. - -However, you may want to use the `arm-none-eabi-ld` linker instead. This can be obtained for Windows/Mac/Linux from the [ARM -Developer Website][arm-dev], or possibly from your OS's package manager. To use it, add the following to your `.cargo/config.toml`: - -```toml -[target.armv5te-none-eabi] -linker = "arm-none-eabi-ld" -``` - -[arm-dev]: https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain - -This target doesn't provide a linker script, you'll need to bring your own -according to the specific device you want to target. Pass -`-Clink-arg=-Tyour_script.ld` as a rustc argument to make the linker use -`your_script.ld` during linking. - -## Building Rust Programs - -Because it is Tier 3, rust does not yet ship pre-compiled artifacts for this target. - -Just use the `build-std` nightly cargo feature to build the `core` library. You -can pass this as a command line argument to cargo, or your `.cargo/config.toml` -file might include the following lines: - -```toml -[unstable] -build-std = ["core"] -``` - -Most of `core` should work as expected, with the following notes: -* the target is "soft float", so `f32` and `f64` operations are emulated in - software. -* integer division is also emulated in software. -* the target is old enough that it doesn't have atomic instructions. - -`alloc` is also supported, as long as you provide your own global allocator. - -Rust programs are output as ELF files. - ## Testing This is a cross-compiled target that you will need to emulate during testing. @@ -63,4 +22,5 @@ This is a cross-compiled target that you will need to emulate during testing. Because this is a device-agnostic target, and the exact emulator that you'll need depends on the specific device you want to run your code on. -For example, when programming for the DS, you can use one of the several available DS emulators, such as [melonDS](https://melonds.kuribo64.net/). +For example, when programming for the DS, you can use one of the several +available DS emulators, such as [melonDS](https://melonds.kuribo64.net/). diff --git a/src/doc/rustc/src/platform-support/armv7r-none-eabi.md b/src/doc/rustc/src/platform-support/armv7r-none-eabi.md new file mode 100644 index 0000000000000..670cead9e006b --- /dev/null +++ b/src/doc/rustc/src/platform-support/armv7r-none-eabi.md @@ -0,0 +1,47 @@ +# `arm(eb)?v7r-none-eabi(hf)?` + +**Tier: 2** + +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]. + +The `eb` versions of this target generate code for big-endian processors. + +See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all +`arm-none-eabi` targets. + +[cortex-r]: https://en.wikipedia.org/wiki/ARM_Cortex-R + +## Target maintainers + +- [Chris Copeland](https://github.com/chrisnc), `chris@chrisnc.net` + +## Requirements + +When using the big-endian version of this target, note that some variants of +the Cortex-R have both big-endian instructions and data. This configuration is +known as BE-32, while data-only big-endianness is known as BE-8. To build +programs for BE-32 processors, the GNU linker must be used with the `-mbe32` +option. See [ARM Cortex-R Series Programmer's Guide: Endianness][endianness] +for more details about different endian modes. + +When using the hardfloat targets, the minimum floating-point features assumed +are those of the `vfpv3-d16`, which includes single- and double-precision, with +16 double-precision registers. This floating-point unit appears in Cortex-R4F +and Cortex-R5F processors. See [VFP in the Cortex-R processors][vfp] +for more details on the possible FPU variants. + +If your processor supports a different set of floating-point features than the +default expectations of `vfpv3-d16`, then these should also be enabled or +disabled as needed with `-C target-feature=(+/-)`. + +[endianness]: https://developer.arm.com/documentation/den0042/a/Coding-for-Cortex-R-Processors/Endianness + +[vfp]: https://developer.arm.com/documentation/den0042/a/Floating-Point/Floating-point-basics-and-the-IEEE-754-standard/VFP-in-the-Cortex-R-processors + +## Cross-compilation toolchains and C code + +This target supports C code compiled with the `arm-none-eabi` target triple and +`-march=armv7-r` or a suitable `-mcpu` flag.