Update the arm-* and aarch64-* platform docs. #146419
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
workingjubilee marked this conversation as resolved.
Show resolved
Hide resolved
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,120 @@ | ||
| # `aarch64-unknown-none` and `aarch64-unknown-none-softfloat` | ||
|
|
||
| **Tier: 2** | ||
|
|
||
| Bare-metal targets for CPUs in the Armv8-A architecture family, running in AArch64 mode. | ||
|
|
||
| For the AArch32 mode carried over from Armv7-A, see | ||
| [`armv7a-none-eabi`](armv7a-none-eabi.md) instead. | ||
|
|
||
| Processors in this family include the [Arm Cortex-A35, 53, 76, etc][aarch64-cpus]. | ||
|
|
||
| [aarch64-cpus]: https://en.wikipedia.org/wiki/Comparison_of_ARM_processors#ARMv8-A | ||
|
|
||
| ## Target maintainers | ||
|
|
||
| * [Rust Embedded Devices Working Group Arm Team] | ||
|
|
||
| [Rust Embedded Devices Working Group Arm Team]: https://github.com/rust-embedded/wg?tab=readme-ov-file#the-arm-team | ||
|
|
||
| ## Target CPU and Target Feature options | ||
|
|
||
| It is possible to tell Rust (or LLVM) that you have a specific model of Arm | ||
| processor, using the [`-Ctarget-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 | ||
| [`-Ctarget-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 | ||
| particular implementation of that CPU may not have those features available. | ||
| In that case, you can use `-Ctarget-feature=-option` to turn off the specific | ||
| CPU features you do not have available, leaving you with the optimized | ||
| instruction scheduling and support for the features you do have. More details | ||
| are available in the detailed target-specific documentation. | ||
|
|
||
| <div class="warning"> | ||
|
|
||
| Many target-features are currently unstable and subject to change, and | ||
| if you use them you should disassemble the compiler output and manually inspect | ||
| it to ensure only appropriate instructions for your CPU have been generated. | ||
|
|
||
| </div> | ||
|
|
||
| If you wish to use the *target-cpu* and *target-feature* options, you can add | ||
| them to your `.cargo/config.toml` file alongside any other flags your project | ||
| uses (likely linker related ones): | ||
|
|
||
| ```toml | ||
| rustflags = [ | ||
| # Usual Arm bare-metal linker setup | ||
| "-Clink-arg=-Tlink.x", | ||
| "-Clink-arg=--nmagic", | ||
| # tell Rust we have a Cortex-A72 | ||
| "-Ctarget-cpu=cortex-a72", | ||
| ] | ||
workingjubilee marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| [build] | ||
| target = "aarch64-unknown-none" | ||
| ``` | ||
|
|
||
| [target-cpu]: https://doc.rust-lang.org/rustc/codegen-options/index.html#target-cpu | ||
| [target-feature]: https://doc.rust-lang.org/rustc/codegen-options/index.html#target-feature | ||
|
|
||
| ## 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.aarch64-unknown-none] | ||
| linker = "aarch64-none-ld" | ||
| ``` | ||
|
|
||
| The GNU linker can also be used by specifying `aarch64-none-gcc` as the | ||
| linker. This is needed when using GCC's link time optimization. | ||
|
|
||
| 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. | ||
|
|
||
| All AArch64 processors include an FPU. The difference between the `-none` and | ||
| `-none-softfloat` targets is whether the FPU is used for passing function arguments. | ||
| You may prefer the `-softfloat` target when writing a kernel or interfacing with | ||
| pre-compiled binaries that use the soft-float ABI. | ||
|
|
||
| When using the hardfloat targets, the minimum floating-point features assumed | ||
| are those of the `fp-armv8`, which excludes NEON SIMD support. If your | ||
| processor supports a different set of floating-point features than the default | ||
| expectations of `fp-armv8`, then these should also be enabled or disabled as | ||
| needed with `-C target-feature=(+/-)`. | ||
workingjubilee marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| [arm-gnu-toolchain]: https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain | ||
|
|
||
| ## 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. | ||
workingjubilee marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| ## Start-up and Low-Level Code | ||
|
|
||
| The [Rust Embedded Devices Working Group Arm Team] maintain the | ||
| [`aarch64-cpu`] crate, which may be useful for writing bare-metal code using | ||
| this target. | ||
|
|
||
| The *TrustedFirmware* group also maintain [Rust crates for this | ||
| target](https://github.com/ArmFirmwareCrates). | ||
|
|
||
| [`aarch64-cpu`]: https://docs.rs/aarch64-cpu | ||
|
Comment on lines
+69
to
+78
There was a problem hiding this comment. I'm not really sure how the maintainers feel about endorsing third-party crates like this. I think this section could just be dropped and, if you really want to have some start-up code, replaced with a tiny linker script + assembly + Rust entrypoint example when e.g. booting with the Linux boot protocol. There was a problem hiding this comment. For many targets the code required is more than can fit into a target doc, and often involves multiple files that would be tedious and error prone to copy-paste into a new project. ArmFirmwareCrates is from Arm themselves, so it seemed legit to refer to it. But I can take it out. I personally find it pretty hard to get started with many of these targets so I think giving people links to code that works and runs is very useful. I’m happy to not have it here, but I don’t know where else it would go. There was a problem hiding this comment. For a target, if the maintainers think it worthwhile to recommend a crate that deals with the special needs of that target, then we generally do not impede such. Often, external software is required anyways for a target, e.g. specialty linkers or compilers or headers or... whatever. If quite a lot of such supplemental material is needed, it may come as an advisory against maintaining the target at all, but this doesn't seem to rise to such a threshold. |
||
|
|
||
| ## Cross-compilation toolchains and C code | ||
|
|
||
| This target supports C code compiled with the `aarch64-unknown-none` target | ||
| triple and a suitable `-march` or `-mcpu` flag. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,54 @@ | ||
| # `armebv7r-none-eabi` and `armebv7r-none-eabihf` | ||
|
|
||
| **Tier: 2** | ||
|
|
||
| Bare-metal target for CPUs in the Armv7-R architecture family running in Big | ||
| Endian mode. These processors support dual ARM/Thumb mode, with ARM mode as | ||
| the default. | ||
|
|
||
| **NOTE:** You should almost always prefer the [little-endian | ||
| versions](armv7r-none-eabi.md) of these target. Big Endian Arm systems are | ||
| highly unusual. | ||
|
|
||
| Processors in this family include the [Arm Cortex-R4, 5, 7, and 8][cortex-r]. | ||
|
|
||
| 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 | ||
|
|
||
| * [@chrisnc](https://github.com/chrisnc) | ||
|
||
|
|
||
| ## Requirements | ||
|
|
||
| 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 | ||
|
|
||
| ## Start-up and Low-Level Code | ||
|
|
||
| The [Rust Embedded Devices Working Group Arm Team] maintain the [`cortex-ar`] | ||
| and [`cortex-r-rt`] crates, which may be useful for writing bare-metal code | ||
| using this target. Those crates include several examples which run in QEMU and | ||
| build using these targets. | ||
|
|
||
| [`cortex-ar`]: https://docs.rs/cortex-ar | ||
| [`cortex-r-rt`]: https://docs.rs/cortex-r-rt | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| # `armv7a-none-eabi` and `armv7a-none-eabihf` | ||
|
|
||
| **Tier: 2** for `armv7a-none-eabi` | ||
| **Tier: 3** for `armv7a-none-eabihf` | ||
|
|
||
| Bare-metal target for CPUs in the Armv7-A architecture family, supporting | ||
| dual ARM/Thumb mode, with ARM mode as the default. | ||
|
|
||
| Note, this is for processors running in AArch32 mode. For the AArch64 mode | ||
| added in Armv8-A, see [`aarch64-unknown-none`](aarch64-unknown-none.md) instead. | ||
|
|
||
| Processors in this family include the [Arm Cortex-A5, 8, 32, etc][cortex-a]. | ||
|
|
||
| See [`arm-none-eabi`](arm-none-eabi.md) for information applicable to all | ||
| `arm-none-eabi` targets. | ||
|
|
||
| [cortex-a]: https://en.wikipedia.org/wiki/ARM_Cortex-A | ||
|
|
||
| ## Target maintainers | ||
|
|
||
| * [Rust Embedded Devices Working Group Arm Team] | ||
|
|
||
| [Rust Embedded Devices Working Group Arm Team]: https://github.com/rust-embedded/wg?tab=readme-ov-file#the-arm-team | ||
|
|
||
| ## Requirements | ||
|
|
||
| Almost all Armv7-A processors include an FPU (a VFPv3 or a VFPv4). The | ||
| difference between the `-eabi` and `-eabihf` targets is whether the FPU is | ||
| used for passing function arguments. You may prefer the `-eabi` soft-float | ||
| target when the processor does not have a floating point unit or the compiled | ||
| code should not use the floating point unit. | ||
|
|
||
| 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-A8 | ||
| and Cortex-A9 processors. See [VFP in the Cortex-A 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=(+/-)`. | ||
|
|
||
| In general, the following four combinations are possible: | ||
|
|
||
| - VFPv3-D16, target feature `+vfp3` and `-d32` | ||
| - VFPv3-D32, target feature `+vfp3` and `+d32` | ||
| - VFPv4-D16, target feature `+vfp4` and `-d32` | ||
| - VFPv4-D32, target feature `+vfp4` and `+d32` | ||
|
|
||
| An Armv7-A processor may optionally include a NEON hardware unit which | ||
| provides Single Instruction Multiple Data (SIMD) operations. The | ||
| implementation of this unit implies VFPv3-D32. The target feature `+neon` may | ||
| be added to inform the compiler about the availability of NEON. | ||
|
|
||
| You can refer to the [arm-none-eabi](arm-none-eabi.md) documentation for a | ||
| generic guide on target feature and target CPU specification and how to enable | ||
| and disable them via `.cargo/config.toml` file. | ||
|
|
||
| [vfp]: https://developer.arm.com/documentation/den0013/0400/Floating-Point/Floating-point-basics-and-the-IEEE-754-standard/ARM-VFP | ||
|
|
||
| ## Start-up and Low-Level Code | ||
|
|
||
| The [Rust Embedded Devices Working Group Arm Team] maintain the [`cortex-ar`] | ||
| and [`cortex-a-rt`] crates, which may be useful for writing bare-metal code | ||
| using this target. The [`cortex-ar` repository](https://github.com/rust-embedded/cortex-ar) | ||
| includes several examples which run in QEMU and build using these targets. | ||
|
|
||
| [`cortex-ar`]: https://docs.rs/cortex-ar | ||
| [`cortex-a-rt`]: https://docs.rs/cortex-a-rt |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.