Skip to content

Commit 9058791

Browse files
matthiaskrgrmatthiaskrgr
authored
Rollup merge of #119102 - chrisnc:arm-none-eabi-docs, r=wesleywiser
Add arm-none-eabi and armv7r-none-eabi platform-support documentation. Mostly collecting existing information that's common to all arm-none-eabi targets and putting it in one file and adding a new file with specific details about armv7r.
2 parents 8b3914c + 90893e4 commit 9058791

File tree

6 files changed

+176
-106
lines changed

6 files changed

+176
-106
lines changed

‎src/doc/rustc/src/SUMMARY.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,10 @@
2222
- [\*-apple-watchos\*](platform-support/apple-watchos.md)
2323
- [aarch64-nintendo-switch-freestanding](platform-support/aarch64-nintendo-switch-freestanding.md)
2424
- [armeb-unknown-linux-gnueabi](platform-support/armeb-unknown-linux-gnueabi.md)
25+
- [arm-none-eabi](platform-support/arm-none-eabi.md)
2526
- [armv4t-none-eabi](platform-support/armv4t-none-eabi.md)
2627
- [armv5te-none-eabi](platform-support/armv5te-none-eabi.md)
28+
- [armv7r-none-eabi](platform-support/armv7r-none-eabi.md)
2729
- [armv6k-nintendo-3ds](platform-support/armv6k-nintendo-3ds.md)
2830
- [armv7-sony-vita-newlibeabihf](platform-support/armv7-sony-vita-newlibeabihf.md)
2931
- [armv7-unknown-linux-uclibceabi](platform-support/armv7-unknown-linux-uclibceabi.md)

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

Lines changed: 21 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -137,17 +137,17 @@ target | std | notes
137137
[`arm-linux-androideabi`](platform-support/android.md) | ✓ | ARMv6 Android
138138
`arm-unknown-linux-musleabi` | ✓ | ARMv6 Linux with MUSL
139139
`arm-unknown-linux-musleabihf` | ✓ | ARMv6 Linux with MUSL, hardfloat
140-
`armebv7r-none-eabi` | * | Bare ARMv7-R, Big Endian
141-
`armebv7r-none-eabihf` | * | Bare ARMv7-R, Big Endian, hardfloat
140+
[`armebv7r-none-eabi`](platform-support/armv7r-none-eabi.md) | * | Bare ARMv7-R, Big Endian
141+
[`armebv7r-none-eabihf`](platform-support/armv7r-none-eabi.md) | * | Bare ARMv7-R, Big Endian, hardfloat
142142
`armv5te-unknown-linux-gnueabi` | ✓ | ARMv5TE Linux (kernel 4.4, glibc 2.23)
143143
`armv5te-unknown-linux-musleabi` | ✓ | ARMv5TE Linux with MUSL
144144
[`armv7-linux-androideabi`](platform-support/android.md) | ✓ | ARMv7-A Android
145145
`armv7-unknown-linux-gnueabi` | ✓ | ARMv7-A Linux (kernel 4.15, glibc 2.27)
146146
`armv7-unknown-linux-musleabi` | ✓ | ARMv7-A Linux with MUSL
147147
`armv7-unknown-linux-musleabihf` | ✓ | ARMv7-A Linux with MUSL, hardfloat
148-
`armv7a-none-eabi` | * | Bare ARMv7-A
149-
`armv7r-none-eabi` | * | Bare ARMv7-R
150-
`armv7r-none-eabihf` | * | Bare ARMv7-R, hardfloat
148+
[`armv7a-none-eabi`](platform-support/arm-none-eabi.md) | * | Bare ARMv7-A
149+
[`armv7r-none-eabi`](platform-support/armv7r-none-eabi.md) | * | Bare ARMv7-R
150+
[`armv7r-none-eabihf`](platform-support/armv7r-none-eabi.md) | * | Bare ARMv7-R, hardfloat
151151
`i586-pc-windows-msvc` | * | 32-bit Windows w/o SSE [^x86_32-floats-x87]
152152
`i586-unknown-linux-gnu` | ✓ | 32-bit Linux w/o SSE (kernel 3.2, glibc 2.17) [^x86_32-floats-x87]
153153
`i586-unknown-linux-musl` | ✓ | 32-bit Linux w/o SSE, MUSL [^x86_32-floats-x87]
@@ -166,15 +166,15 @@ target | std | notes
166166
`riscv64imac-unknown-none-elf` | * | Bare RISC-V (RV64IMAC ISA)
167167
`sparc64-unknown-linux-gnu` | ✓ | SPARC Linux (kernel 4.4, glibc 2.23)
168168
`sparcv9-sun-solaris` | ✓ | SPARC Solaris 11, illumos
169-
`thumbv6m-none-eabi` | * | Bare ARMv6-M
170-
`thumbv7em-none-eabi` | * | Bare ARMv7E-M
171-
`thumbv7em-none-eabihf` | * | Bare ARMV7E-M, hardfloat
172-
`thumbv7m-none-eabi` | * | Bare ARMv7-M
169+
[`thumbv6m-none-eabi`](platform-support/arm-none-eabi.md) | * | Bare ARMv6-M
170+
[`thumbv7em-none-eabi`](platform-support/arm-none-eabi.md) | * | Bare ARMv7E-M
171+
[`thumbv7em-none-eabihf`](platform-support/arm-none-eabi.md) | * | Bare ARMV7E-M, hardfloat
172+
[`thumbv7m-none-eabi`](platform-support/arm-none-eabi.md) | * | Bare ARMv7-M
173173
[`thumbv7neon-linux-androideabi`](platform-support/android.md) | ✓ | Thumb2-mode ARMv7-A Android with NEON
174174
`thumbv7neon-unknown-linux-gnueabihf` | ✓ | Thumb2-mode ARMv7-A Linux with NEON (kernel 4.4, glibc 2.23)
175-
`thumbv8m.base-none-eabi` | * | Bare ARMv8-M Baseline
176-
`thumbv8m.main-none-eabi` | * | Bare ARMv8-M Mainline
177-
`thumbv8m.main-none-eabihf` | * | Bare ARMv8-M Mainline, hardfloat
175+
[`thumbv8m.base-none-eabi`](platform-support/arm-none-eabi.md) | * | Bare ARMv8-M Baseline
176+
[`thumbv8m.main-none-eabi`](platform-support/arm-none-eabi.md) | * | Bare ARMv8-M Mainline
177+
[`thumbv8m.main-none-eabihf`](platform-support/arm-none-eabi.md) | * | Bare ARMv8-M Mainline, hardfloat
178178
`wasm32-unknown-emscripten` | ✓ | WebAssembly via Emscripten
179179
`wasm32-unknown-unknown` | ✓ | WebAssembly
180180
`wasm32-wasi` | ✓ | WebAssembly with WASI
@@ -239,11 +239,11 @@ target | std | host | notes
239239
`aarch64_be-unknown-linux-gnu_ilp32` | ✓ | ✓ | ARM64 Linux (big-endian, ILP32 ABI)
240240
`aarch64_be-unknown-linux-gnu` | ✓ | ✓ | ARM64 Linux (big-endian)
241241
[`aarch64_be-unknown-netbsd`](platform-support/netbsd.md) | ✓ | ✓ | ARM64 NetBSD (big-endian)
242-
[`arm64_32-apple-watchos`](platform-support/apple-watchos.md) | ✓ | | ARM Apple WatchOS 64-bit with 32-bit pointers
242+
[`arm64_32-apple-watchos`](platform-support/apple-watchos.md) | ✓ | | ARM Apple WatchOS 64-bit with 32-bit pointers
243243
[`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).
244-
`armv4t-none-eabi` | * | | Bare ARMv4T
244+
[`armv4t-none-eabi`](platform-support/armv4t-none-eabi.md) | * | | Bare ARMv4T
245245
`armv4t-unknown-linux-gnueabi` | ? | | ARMv4T Linux
246-
[`armv5te-none-eabi`](platform-support/armv5te-none-eabi.md) | * | | Bare ARMv5TE
246+
[`armv5te-none-eabi`](platform-support/armv5te-none-eabi.md) | * | | Bare ARMv5TE
247247
`armv5te-unknown-linux-uclibceabi` | ? | | ARMv5TE Linux with uClibc
248248
`armv6-unknown-freebsd` | ✓ | ✓ | ARMv6 FreeBSD
249249
[`armv6-unknown-netbsd-eabihf`](platform-support/netbsd.md) | ✓ | ✓ | ARMv6 NetBSD w/hard-float
@@ -257,8 +257,8 @@ target | std | host | notes
257257
`armv7-wrs-vxworks-eabihf` | ? | | ARMv7-A for VxWorks
258258
[`armv7a-kmc-solid_asp3-eabi`](platform-support/kmc-solid.md) | ✓ | | ARM SOLID with TOPPERS/ASP3
259259
[`armv7a-kmc-solid_asp3-eabihf`](platform-support/kmc-solid.md) | ✓ | | ARM SOLID with TOPPERS/ASP3, hardfloat
260-
`armv7a-none-eabihf` | * | | Bare ARMv7-A, hardfloat
261-
[`armv7k-apple-watchos`](platform-support/apple-watchos.md) | ✓ | | ARMv7-A Apple WatchOS
260+
[`armv7a-none-eabihf`](platform-support/arm-none-eabi.md) | * | | Bare ARMv7-A, hardfloat
261+
[`armv7k-apple-watchos`](platform-support/apple-watchos.md) | ✓ | | ARMv7-A Apple WatchOS
262262
`armv7s-apple-ios` | ✓ | | ARMv7-A Apple-A6 Apple iOS
263263
`avr-unknown-gnu-atmega328` | * | | AVR. Requires `-Z build-std=core`
264264
`bpfeb-unknown-none` | * | | BPF (big endian)
@@ -333,15 +333,15 @@ target | std | host | notes
333333
[`sparc-unknown-none-elf`](./platform-support/sparc-unknown-none-elf.md) | * | | Bare 32-bit SPARC V7+
334334
[`sparc64-unknown-netbsd`](platform-support/netbsd.md) | ✓ | ✓ | NetBSD/sparc64
335335
[`sparc64-unknown-openbsd`](platform-support/openbsd.md) | ✓ | ✓ | OpenBSD/sparc64
336-
`thumbv4t-none-eabi` | * | | Thumb-mode Bare ARMv4T
337-
[`thumbv5te-none-eabi`](platform-support/armv5te-none-eabi.md) | * | | Thumb-mode Bare ARMv5TE
336+
[`thumbv4t-none-eabi`](platform-support/armv4t-none-eabi.md) | * | | Thumb-mode Bare ARMv4T
337+
[`thumbv5te-none-eabi`](platform-support/armv5te-none-eabi.md) | * | | Thumb-mode Bare ARMv5TE
338338
`thumbv7a-pc-windows-msvc` | ? | |
339339
`thumbv7a-uwp-windows-msvc` | ✓ | |
340340
`thumbv7neon-unknown-linux-musleabihf` | ? | | Thumb2-mode ARMv7-A Linux with NEON, MUSL
341341
[`wasm64-unknown-unknown`](platform-support/wasm64-unknown-unknown.md) | ? | | WebAssembly
342342
`x86_64-apple-ios-macabi` | ✓ | | Apple Catalyst on x86_64
343-
[`x86_64-apple-tvos`](platform-support/apple-tvos.md) | ? | | x86 64-bit tvOS
344-
[`x86_64-apple-watchos-sim`](platform-support/apple-watchos.md) | ✓ | | x86 64-bit Apple WatchOS simulator
343+
[`x86_64-apple-tvos`](platform-support/apple-tvos.md) | ? | | x86 64-bit tvOS
344+
[`x86_64-apple-watchos-sim`](platform-support/apple-watchos.md) | ✓ | | x86 64-bit Apple WatchOS simulator
345345
[`x86_64-pc-nto-qnx710`](platform-support/nto-qnx.md) | ✓ | | x86 64-bit QNX Neutrino 7.1 RTOS |
346346
[`x86_64-pc-windows-gnullvm`](platform-support/pc-windows-gnullvm.md) | ✓ | ✓ |
347347
`x86_64-pc-windows-msvc` | * | | 64-bit Windows XP support

‎src/doc/rustc/src/platform-support/arm-none-eabi.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# `{arm,thumb}*-none-eabi(hf)?`
2+
3+
**Tier: 2**
4+
- [arm(eb)?v7r-none-eabi(hf)?](armv7r-none-eabi.md)
5+
- armv7a-none-eabi
6+
- thumbv6m-none-eabi
7+
- thumbv7m-none-eabi
8+
- thumbv7em-none-eabi(hf)?
9+
- thumbv8m.base-none-eabi
10+
- thumbv8m.main-none-eabi(hf)?
11+
12+
**Tier: 3**
13+
- [{arm,thumb}v4t-none-eabi](armv4t-none-eabi.md)
14+
- [{arm,thumb}v5te-none-eabi](armv5te-none-eabi.md)
15+
- armv7a-none-eabihf
16+
17+
Bare-metal target for 32-bit ARM CPUs.
18+
19+
If a target has a `*hf` variant, that variant uses the hardware floating-point
20+
ABI and enables some minimum set of floating-point features based on the FPU(s)
21+
available in that processor family.
22+
23+
## Requirements
24+
25+
These targets are cross-compiled and use static linking.
26+
27+
By default, the `lld` linker included with Rust will be used; however, you may
28+
want to use the GNU linker instead. This can be obtained for Windows/Mac/Linux
29+
from the [Arm Developer Website][arm-gnu-toolchain], or possibly from your OS's
30+
package manager. To use it, add the following to your `.cargo/config.toml`:
31+
32+
```toml
33+
[target.<your-target>]
34+
linker = "arm-none-eabi-ld"
35+
```
36+
37+
The GNU linker can also be used by specifying `arm-none-eabi-gcc` as the
38+
linker. This is needed when using GCC's link time optimization.
39+
40+
[arm-gnu-toolchain]: https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain
41+
42+
These targets don't provide a linker script, so you'll need to bring your own
43+
according to the specific device you are using. Pass
44+
`-Clink-arg=-Tyour_script.ld` as a rustc argument to make the linker use
45+
`your_script.ld` during linking.
46+
47+
Targets named `thumb*` instead of `arm*`
48+
generate Thumb-mode code by default. M-profile processors (`thumbv*m*-*`
49+
targets) only support Thumb-mode code.
50+
For the `arm*` targets, Thumb-mode code generation can be enabled by using
51+
`-C target-feature=+thumb-mode`. Using the unstable
52+
`#![feature(arm_target_feature)]`, the attribute
53+
`#[target_feature(enable = "thumb-mode")]` can be applied to individual
54+
`unsafe` functions to cause those functions to be compiled to Thumb-mode code.
55+
56+
## Building Rust Programs
57+
58+
For the Tier 3 targets in this family, rust does not ship pre-compiled
59+
artifacts.
60+
61+
Just use the `build-std` nightly cargo feature to build the `core` library. You
62+
can pass this as a command line argument to cargo, or your `.cargo/config.toml`
63+
file might include the following lines:
64+
65+
```toml
66+
[unstable]
67+
build-std = ["core"]
68+
```
69+
70+
Most of `core` should work as expected, with the following notes:
71+
* If the target is not `*hf`, then floating-point operations are emulated in
72+
software.
73+
* Integer division is also emulated in software on some targets, depending on
74+
the CPU.
75+
* Architectures prior to ARMv7 don't have atomic instructions.
76+
77+
`alloc` is also supported, as long as you provide your own global allocator.
78+
79+
Rust programs are output as ELF files.
80+
81+
## Testing
82+
83+
This is a cross-compiled target that you will need to emulate during testing.
84+
85+
The exact emulator that you'll need depends on the specific device you want to
86+
run your code on.
87+
88+
## Cross-compilation toolchains and C code
89+
90+
The target supports C code compiled with the `arm-none-eabi` target triple and
91+
a suitable `-march` or `-mcpu` flag.
92+
93+
`gcc` or `clang` can be used, but note that `gcc` uses `-fshort-enums` by
94+
default for `arm-none*` targets, while `clang` does not. `rustc` matches the
95+
`gcc` behavior, i.e., the size of a `#[repr(C)] enum` in Rust can be as little
96+
as 1 byte, rather than 4, as they are on `arm-linux` targets.

‎src/doc/rustc/src/platform-support/armv4t-none-eabi.md‎

Lines changed: 5 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -6,51 +6,16 @@ Bare-metal target for any cpu in the ARMv4T architecture family, supporting
66
ARM/Thumb code interworking (aka `a32`/`t32`), with ARM code as the default code
77
generation.
88

9-
In particular this supports the Gameboy Advance (GBA), but there's nothing GBA
10-
specific with this target, so any ARMv4T device should work fine.
9+
In particular this supports the Game Boy Advance (GBA), but there's nothing
10+
GBA-specific with this target, so any ARMv4T device should work fine.
11+
12+
See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all
13+
`arm-none-eabi` targets.
1114

1215
## Target Maintainers
1316

1417
* [@Lokathor](https://github.com/lokathor)
1518

16-
## Requirements
17-
18-
The target is cross-compiled, and uses static linking.
19-
20-
This target doesn't provide a linker script, you'll need to bring your own
21-
according to the specific device you want to target. Pass
22-
`-Clink-arg=-Tyour_script.ld` as a rustc argument to make the linker use
23-
`your_script.ld` during linking.
24-
25-
## Building Rust Programs
26-
27-
Because it is Tier 3, rust does not yet ship pre-compiled artifacts for this target.
28-
29-
Just use the `build-std` nightly cargo feature to build the `core` library. You
30-
can pass this as a command line argument to cargo, or your `.cargo/config.toml`
31-
file might include the following lines:
32-
33-
```toml
34-
[unstable]
35-
build-std = ["core"]
36-
```
37-
38-
Most of `core` should work as expected, with the following notes:
39-
* the target is "soft float", so `f32` and `f64` operations are emulated in
40-
software.
41-
* integer division is also emulated in software.
42-
* the target is old enough that it doesn't have atomic instructions.
43-
44-
Rust programs are output as ELF files.
45-
46-
For running on hardware, you'll generally need to extract the "raw" program code
47-
out of the ELF and into a file of its own. The `objcopy` program provided as
48-
part of the GNU Binutils can do this:
49-
50-
```shell
51-
arm-none-eabi-objcopy --output-target binary [in_file] [out_file]
52-
```
53-
5419
## Testing
5520

5621
This is a cross-compiled target that you will need to emulate during testing.

‎src/doc/rustc/src/platform-support/armv5te-none-eabi.md‎

Lines changed: 5 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -8,59 +8,19 @@ generation.
88

99
The `thumbv5te-none-eabi` target is the same as this one, but the instruction set defaults to `t32`.
1010

11+
See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all
12+
`arm-none-eabi` targets.
13+
1114
## Target Maintainers
1215

1316
* [@QuinnPainter](https://github.com/QuinnPainter)
1417

15-
## Requirements
16-
17-
The target is cross-compiled, and uses static linking.
18-
19-
By default, the `lld` linker included with Rust will be used.
20-
21-
However, you may want to use the `arm-none-eabi-ld` linker instead. This can be obtained for Windows/Mac/Linux from the [ARM
22-
Developer Website][arm-dev], or possibly from your OS's package manager. To use it, add the following to your `.cargo/config.toml`:
23-
24-
```toml
25-
[target.armv5te-none-eabi]
26-
linker = "arm-none-eabi-ld"
27-
```
28-
29-
[arm-dev]: https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain
30-
31-
This target doesn't provide a linker script, you'll need to bring your own
32-
according to the specific device you want to target. Pass
33-
`-Clink-arg=-Tyour_script.ld` as a rustc argument to make the linker use
34-
`your_script.ld` during linking.
35-
36-
## Building Rust Programs
37-
38-
Because it is Tier 3, rust does not yet ship pre-compiled artifacts for this target.
39-
40-
Just use the `build-std` nightly cargo feature to build the `core` library. You
41-
can pass this as a command line argument to cargo, or your `.cargo/config.toml`
42-
file might include the following lines:
43-
44-
```toml
45-
[unstable]
46-
build-std = ["core"]
47-
```
48-
49-
Most of `core` should work as expected, with the following notes:
50-
* the target is "soft float", so `f32` and `f64` operations are emulated in
51-
software.
52-
* integer division is also emulated in software.
53-
* the target is old enough that it doesn't have atomic instructions.
54-
55-
`alloc` is also supported, as long as you provide your own global allocator.
56-
57-
Rust programs are output as ELF files.
58-
5918
## Testing
6019

6120
This is a cross-compiled target that you will need to emulate during testing.
6221

6322
Because this is a device-agnostic target, and the exact emulator that you'll
6423
need depends on the specific device you want to run your code on.
6524

66-
For example, when programming for the DS, you can use one of the several available DS emulators, such as [melonDS](https://melonds.kuribo64.net/).
25+
For example, when programming for the DS, you can use one of the several
26+
available DS emulators, such as [melonDS](https://melonds.kuribo64.net/).

‎src/doc/rustc/src/platform-support/armv7r-none-eabi.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# `arm(eb)?v7r-none-eabi(hf)?`
2+
3+
**Tier: 2**
4+
5+
Bare-metal target for CPUs in the ARMv7-R architecture family, supporting
6+
dual ARM/Thumb mode, with ARM mode as the default.
7+
8+
Processors in this family include the [Arm Cortex-R4, 5, 7, and 8][cortex-r].
9+
10+
The `eb` versions of this target generate code for big-endian processors.
11+
12+
See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all
13+
`arm-none-eabi` targets.
14+
15+
[cortex-r]: https://en.wikipedia.org/wiki/ARM_Cortex-R
16+
17+
## Target maintainers
18+
19+
- [Chris Copeland](https://github.com/chrisnc), `chris@chrisnc.net`
20+
21+
## Requirements
22+
23+
When using the big-endian version of this target, note that some variants of
24+
the Cortex-R have both big-endian instructions and data. This configuration is
25+
known as BE-32, while data-only big-endianness is known as BE-8. To build
26+
programs for BE-32 processors, the GNU linker must be used with the `-mbe32`
27+
option. See [ARM Cortex-R Series Programmer's Guide: Endianness][endianness]
28+
for more details about different endian modes.
29+
30+
When using the hardfloat targets, the minimum floating-point features assumed
31+
are those of the `vfpv3-d16`, which includes single- and double-precision, with
32+
16 double-precision registers. This floating-point unit appears in Cortex-R4F
33+
and Cortex-R5F processors. See [VFP in the Cortex-R processors][vfp]
34+
for more details on the possible FPU variants.
35+
36+
If your processor supports a different set of floating-point features than the
37+
default expectations of `vfpv3-d16`, then these should also be enabled or
38+
disabled as needed with `-C target-feature=(+/-)`.
39+
40+
[endianness]: https://developer.arm.com/documentation/den0042/a/Coding-for-Cortex-R-Processors/Endianness
41+
42+
[vfp]: https://developer.arm.com/documentation/den0042/a/Floating-Point/Floating-point-basics-and-the-IEEE-754-standard/VFP-in-the-Cortex-R-processors
43+
44+
## Cross-compilation toolchains and C code
45+
46+
This target supports C code compiled with the `arm-none-eabi` target triple and
47+
`-march=armv7-r` or a suitable `-mcpu` flag.

0 commit comments

Comments
 (0)