From a126c110d9024fc5e87a4a202918c95df0798ef8 Mon Sep 17 00:00:00 2001 From: Lokathor Date: Tue, 28 May 2024 16:07:48 -0600 Subject: [PATCH 1/6] Reorder the TOC so that targets are put under their meta-group --- src/doc/rustc/src/SUMMARY.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md index c9c0ee4067f1b..2de13218e4955 100644 --- a/src/doc/rustc/src/SUMMARY.md +++ b/src/doc/rustc/src/SUMMARY.md @@ -26,10 +26,15 @@ - [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) - - [armv8r-none-eabihf](platform-support/armv8r-none-eabihf.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) + - [armv8r-none-eabihf](platform-support/armv8r-none-eabihf.md) + - [thumbv6m-none-eabi](./platform-support/thumbv6m-none-eabi.md) + - [thumbv7em-none-eabi\*](./platform-support/thumbv7em-none-eabi.md) + - [thumbv7m-none-eabi](./platform-support/thumbv7m-none-eabi.md) + - [thumbv8m.base-none-eabi](./platform-support/thumbv8m.base-none-eabi.md) + - [thumbv8m.main-none-eabi\*](./platform-support/thumbv8m.main-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) @@ -56,11 +61,6 @@ - [riscv32imac-unknown-xous-elf](platform-support/riscv32imac-unknown-xous-elf.md) - [riscv32*-unknown-none-elf](platform-support/riscv32-unknown-none-elf.md) - [sparc-unknown-none-elf](./platform-support/sparc-unknown-none-elf.md) - - [thumbv6m-none-eabi](./platform-support/thumbv6m-none-eabi.md) - - [thumbv7m-none-eabi](./platform-support/thumbv7m-none-eabi.md) - - [thumbv7em-none-eabi\*](./platform-support/thumbv7em-none-eabi.md) - - [thumbv8m.base-none-eabi](./platform-support/thumbv8m.base-none-eabi.md) - - [thumbv8m.main-none-eabi\*](./platform-support/thumbv8m.main-none-eabi.md) - [*-pc-windows-gnullvm](platform-support/pc-windows-gnullvm.md) - [\*-nto-qnx-\*](platform-support/nto-qnx.md) - [*-unikraft-linux-musl](platform-support/unikraft-linux-musl.md) From f6463142eecb238379e6ca06b81578ab0d8e1d32 Mon Sep 17 00:00:00 2001 From: Lokathor Date: Tue, 28 May 2024 16:15:28 -0600 Subject: [PATCH 2/6] make the fact that arm-none-eabi is a group of targets the first thing you see on the page. --- .../src/platform-support/arm-none-eabi.md | 26 ++++++++++++------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/src/doc/rustc/src/platform-support/arm-none-eabi.md b/src/doc/rustc/src/platform-support/arm-none-eabi.md index 0b1b10e4762e7..09be74a805d14 100644 --- a/src/doc/rustc/src/platform-support/arm-none-eabi.md +++ b/src/doc/rustc/src/platform-support/arm-none-eabi.md @@ -1,6 +1,15 @@ # `{arm,thumb}*-none-eabi(hf)?` -## Tier 2 Target List +## Common Target Details + +This documentation covers details that apply to a range of bare-metal targets +for 32-bit Arm CPUs. The `arm-none-eabi` flavor of the GNU compiler toolchain is +often used to assist compilation to these targets. + +Details that apply only to only a specific target in this group are covered in +their own document. + +### Tier 2 Target List - Arm A-Profile Architectures - `armv7a-none-eabi` @@ -16,7 +25,7 @@ - *Legacy* Arm Architectures - None -## Tier 3 Target List +### Tier 3 Target List - Arm A-Profile Architectures - `armv7a-none-eabihf` @@ -28,11 +37,7 @@ - [`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 targets -for 32-bit Arm CPUs. In addition, target specific details may be covered in -their own document. +## Instruction Sets There are two 32-bit instruction set architectures (ISAs) defined by Arm: @@ -43,9 +48,10 @@ There are two 32-bit instruction set architectures (ISAs) defined by Arm: - The [*T32 ISA*][t32-isa], with a mix of 16-bit and 32-bit width instructions. Note that this term includes both the original 16-bit width *Thumb* ISA introduced with the Armv4T architecture in 1994, and the later 16/32-bit sized - *Thumb-2* ISA introduced with the Armv6T2 architecture in 2003. Again, these - ISAs have been revised by subsequent revisions to the relevant Arm - architecture specifications. + *Thumb-2* ISA introduced with the Armv6T2 architecture in 2003. + +Again, these ISAs have been revised by subsequent revisions to the relevant Arm +architecture specifications. There is also a 64-bit ISA with fixed-width 32-bit instructions called the *A64 ISA*, but targets which implement that instruction set generally start with From 144adf6787bbd25913bfd9b6288acf4d337555a0 Mon Sep 17 00:00:00 2001 From: Lokathor Date: Tue, 28 May 2024 17:08:19 -0600 Subject: [PATCH 3/6] update armv4t docs --- .../src/platform-support/armv4t-none-eabi.md | 21 ++++++++----------- 1 file changed, 9 insertions(+), 12 deletions(-) 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 f4c8dd46f1d03..ab8b4caaadffa 100644 --- a/src/doc/rustc/src/platform-support/armv4t-none-eabi.md +++ b/src/doc/rustc/src/platform-support/armv4t-none-eabi.md @@ -1,16 +1,13 @@ -# armv4t-none-eabi +# armv4t-none-eabi / thumbv4t-none-eabi Tier 3 -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. +These two targets are part of the [`arm-none-eabi`](arm-none-eabi.md) target +group, and all the information there applies. -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. +Both of these targets can be used on the Game Boy Advance (GBA), among other +things. On the GBA, one should usually use the `thumb` target to get the best +overall performance. ## Target Maintainers @@ -23,6 +20,6 @@ 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 Gameboy Advance, the -[mgba-test-runner](https://github.com/agbrs/agb) program could be used to make a -normal set of rust tests be run within the `mgba` emulator. +* When building for the GBA, [mgba-test-runner](https://github.com/agbrs/agb) + can be used to make a normal set of rust tests be run within the `mgba` + emulator. From d8704b9ac6e72c68920c08a559ce1eba264bef03 Mon Sep 17 00:00:00 2001 From: Lokathor Date: Tue, 28 May 2024 17:16:36 -0600 Subject: [PATCH 4/6] It's spelled "ARM", in all caps. --- .../src/platform-support/arm-none-eabi.md | 44 +++++++++---------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/src/doc/rustc/src/platform-support/arm-none-eabi.md b/src/doc/rustc/src/platform-support/arm-none-eabi.md index 09be74a805d14..aa8ab296fba5c 100644 --- a/src/doc/rustc/src/platform-support/arm-none-eabi.md +++ b/src/doc/rustc/src/platform-support/arm-none-eabi.md @@ -3,7 +3,7 @@ ## Common Target Details This documentation covers details that apply to a range of bare-metal targets -for 32-bit Arm CPUs. The `arm-none-eabi` flavor of the GNU compiler toolchain is +for 32-bit ARM CPUs. The `arm-none-eabi` flavor of the GNU compiler toolchain is often used to assist compilation to these targets. Details that apply only to only a specific target in this group are covered in @@ -11,55 +11,55 @@ their own document. ### Tier 2 Target List -- Arm A-Profile Architectures +- ARM A-Profile Architectures - `armv7a-none-eabi` -- Arm R-Profile Architectures +- 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 +- ARM M-Profile Architectures - [`thumbv6m-none-eabi`](thumbv6m-none-eabi.md) - [`thumbv7m-none-eabi`](thumbv7m-none-eabi.md) - [`thumbv7em-none-eabi` and `thumbv7em-none-eabihf`](thumbv7em-none-eabi.md) - [`thumbv8m.base-none-eabi`](thumbv8m.base-none-eabi.md) - [`thumbv8m.main-none-eabi` and `thumbv8m.main-none-eabihf`](thumbv8m.main-none-eabi.md) -- *Legacy* Arm Architectures +- *Legacy* ARM Architectures - None ### Tier 3 Target List -- Arm A-Profile Architectures +- ARM A-Profile Architectures - `armv7a-none-eabihf` -- Arm R-Profile Architectures +- ARM R-Profile Architectures - [`armv8r-none-eabihf`](armv8r-none-eabihf.md) -- Arm M-Profile Architectures +- ARM M-Profile Architectures - None -- *Legacy* Arm Architectures +- *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) ## Instruction Sets -There are two 32-bit instruction set architectures (ISAs) defined by Arm: +There are two 32-bit instruction set architectures (ISAs) defined by ARM: - The [*A32 ISA*][a32-isa], with fixed-width 32-bit instructions. Previously - known as the *Arm* ISA, this originated with the original ARM1 of 1985 and has + known as the *ARM* ISA, this originated with the original ARM1 of 1985 and has been updated by various revisions to the architecture specifications ever since. - The [*T32 ISA*][t32-isa], with a mix of 16-bit and 32-bit width instructions. Note that this term includes both the original 16-bit width *Thumb* ISA - introduced with the Armv4T architecture in 1994, and the later 16/32-bit sized - *Thumb-2* ISA introduced with the Armv6T2 architecture in 2003. + introduced with the ARMv4T architecture in 1994, and the later 16/32-bit sized + *Thumb-2* ISA introduced with the ARMv6T2 architecture in 2003. -Again, these ISAs have been revised by subsequent revisions to the relevant Arm +Again, these ISAs have been revised by subsequent revisions to the relevant ARM architecture specifications. There is also a 64-bit ISA with fixed-width 32-bit instructions called the *A64 ISA*, but targets which implement that instruction set generally start with `aarch64*` and are discussed elsewhere. -Rust targets starting with `arm*` generate Arm (A32) code by default, whilst -targets named `thumb*` generate Thumb (T32) code by default. Most Arm chips -support both Thumb mode and Arm mode, with the notable exception that M-profile +Rust targets starting with `arm*` generate ARM (A32) code by default, whilst +targets named `thumb*` generate Thumb (T32) code by default. Most ARM chips +support both Thumb mode and ARM mode, with the notable exception that M-profile processors (`thumbv*m*-none-eabi*` targets) *only* support Thumb-mode. Rust targets ending with `eabi` use the so-called *soft-float ABI*: functions @@ -92,14 +92,14 @@ instructions. ## Target CPU and Target Feature options -It is possible to tell Rust (or LLVM) that you have a specific model of Arm +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 Advanced SIMD 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 +*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 optimized instruction @@ -116,7 +116,7 @@ uses (likely linker related ones): ```toml rustflags = [ - # Usual Arm bare-metal linker setup + # Usual ARM bare-metal linker setup "-Clink-arg=-Tlink.x", "-Clink-arg=--nmagic", # tell Rust we have a Cortex-M55 @@ -139,7 +139,7 @@ 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 +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 @@ -185,7 +185,7 @@ Most of `core` should work as expected, with the following notes: specific kind of FPU) * Integer division is also emulated in software on some targets, depending on the target, `target-cpu` and `target-feature`s. -* Older Arm architectures (e.g. Armv4, Armv5TE and Armv6-M) are limited to basic +* 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]. From bb1f5c38c053905953e7310f9e2d9e29acfc3ad9 Mon Sep 17 00:00:00 2001 From: Lokathor Date: Tue, 28 May 2024 17:30:30 -0600 Subject: [PATCH 5/6] delete the offending single space. --- src/doc/rustc/src/platform-support/arm-none-eabi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/rustc/src/platform-support/arm-none-eabi.md b/src/doc/rustc/src/platform-support/arm-none-eabi.md index aa8ab296fba5c..09f3461cb9807 100644 --- a/src/doc/rustc/src/platform-support/arm-none-eabi.md +++ b/src/doc/rustc/src/platform-support/arm-none-eabi.md @@ -5,7 +5,7 @@ This documentation covers details that apply to a range of bare-metal targets for 32-bit ARM CPUs. The `arm-none-eabi` flavor of the GNU compiler toolchain is often used to assist compilation to these targets. - + Details that apply only to only a specific target in this group are covered in their own document. From 94d4040925571c7a69cebe6c6e9aeab172da65d1 Mon Sep 17 00:00:00 2001 From: Lokathor Date: Thu, 30 May 2024 19:34:05 -0600 Subject: [PATCH 6/6] The modern styling is apparently to use Title Case for the chip/company, "Arm". --- .../src/platform-support/arm-none-eabi.md | 44 +++++++++---------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/src/doc/rustc/src/platform-support/arm-none-eabi.md b/src/doc/rustc/src/platform-support/arm-none-eabi.md index 09f3461cb9807..de0ef322fa673 100644 --- a/src/doc/rustc/src/platform-support/arm-none-eabi.md +++ b/src/doc/rustc/src/platform-support/arm-none-eabi.md @@ -3,7 +3,7 @@ ## Common Target Details This documentation covers details that apply to a range of bare-metal targets -for 32-bit ARM CPUs. The `arm-none-eabi` flavor of the GNU compiler toolchain is +for 32-bit Arm CPUs. The `arm-none-eabi` flavor of the GNU compiler toolchain is often used to assist compilation to these targets. Details that apply only to only a specific target in this group are covered in @@ -11,55 +11,55 @@ their own document. ### Tier 2 Target List -- ARM A-Profile Architectures +- Arm A-Profile Architectures - `armv7a-none-eabi` -- ARM R-Profile Architectures +- 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 +- Arm M-Profile Architectures - [`thumbv6m-none-eabi`](thumbv6m-none-eabi.md) - [`thumbv7m-none-eabi`](thumbv7m-none-eabi.md) - [`thumbv7em-none-eabi` and `thumbv7em-none-eabihf`](thumbv7em-none-eabi.md) - [`thumbv8m.base-none-eabi`](thumbv8m.base-none-eabi.md) - [`thumbv8m.main-none-eabi` and `thumbv8m.main-none-eabihf`](thumbv8m.main-none-eabi.md) -- *Legacy* ARM Architectures +- *Legacy* Arm Architectures - None ### Tier 3 Target List -- ARM A-Profile Architectures +- Arm A-Profile Architectures - `armv7a-none-eabihf` -- ARM R-Profile Architectures +- Arm R-Profile Architectures - [`armv8r-none-eabihf`](armv8r-none-eabihf.md) -- ARM M-Profile Architectures +- Arm M-Profile Architectures - None -- *Legacy* ARM Architectures +- *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) ## Instruction Sets -There are two 32-bit instruction set architectures (ISAs) defined by ARM: +There are two 32-bit instruction set architectures (ISAs) defined by Arm: - The [*A32 ISA*][a32-isa], with fixed-width 32-bit instructions. Previously - known as the *ARM* ISA, this originated with the original ARM1 of 1985 and has + known as the *Arm* ISA, this originated with the original Arm1 of 1985 and has been updated by various revisions to the architecture specifications ever since. - The [*T32 ISA*][t32-isa], with a mix of 16-bit and 32-bit width instructions. Note that this term includes both the original 16-bit width *Thumb* ISA - introduced with the ARMv4T architecture in 1994, and the later 16/32-bit sized - *Thumb-2* ISA introduced with the ARMv6T2 architecture in 2003. + introduced with the Armv4T architecture in 1994, and the later 16/32-bit sized + *Thumb-2* ISA introduced with the Armv6T2 architecture in 2003. -Again, these ISAs have been revised by subsequent revisions to the relevant ARM +Again, these ISAs have been revised by subsequent revisions to the relevant Arm architecture specifications. There is also a 64-bit ISA with fixed-width 32-bit instructions called the *A64 ISA*, but targets which implement that instruction set generally start with `aarch64*` and are discussed elsewhere. -Rust targets starting with `arm*` generate ARM (A32) code by default, whilst -targets named `thumb*` generate Thumb (T32) code by default. Most ARM chips -support both Thumb mode and ARM mode, with the notable exception that M-profile +Rust targets starting with `arm*` generate Arm (A32) code by default, whilst +targets named `thumb*` generate Thumb (T32) code by default. Most Arm chips +support both Thumb mode and Arm mode, with the notable exception that M-profile processors (`thumbv*m*-none-eabi*` targets) *only* support Thumb-mode. Rust targets ending with `eabi` use the so-called *soft-float ABI*: functions @@ -92,14 +92,14 @@ instructions. ## Target CPU and Target Feature options -It is possible to tell Rust (or LLVM) that you have a specific model of ARM +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 Advanced SIMD 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 +*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 optimized instruction @@ -116,7 +116,7 @@ uses (likely linker related ones): ```toml rustflags = [ - # Usual ARM bare-metal linker setup + # Usual Arm bare-metal linker setup "-Clink-arg=-Tlink.x", "-Clink-arg=--nmagic", # tell Rust we have a Cortex-M55 @@ -139,7 +139,7 @@ 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 +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 @@ -185,7 +185,7 @@ Most of `core` should work as expected, with the following notes: specific kind of FPU) * Integer division is also emulated in software on some targets, depending on the target, `target-cpu` and `target-feature`s. -* Older ARM architectures (e.g. ARMv4, ARMv5TE and ARMv6-M) are limited to basic +* 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].