ARM Target Docs Update

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)

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,24 +37,21 @@
   - [`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:
 
 - 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. 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

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.