|
| 1 | +# `aarch64-unknown-none` |
| 2 | + |
| 3 | +**Tier: 2** |
| 4 | + |
| 5 | +Bare-metal target for CPUs in the Armv8-A architecture family, running in AArch64 mode. |
| 6 | + |
| 7 | +For the AArch32 mode carried over from Armv7-A, see |
| 8 | +[`armv7a-none-eabi`](armv7a-none-eabi.md) instead. |
| 9 | + |
| 10 | +Processors in this family include the [Arm Cortex-A35, 53, 76, etc][aarch64-cpus]. |
| 11 | + |
| 12 | +[aarch64-cpus]: https://en.wikipedia.org/wiki/Comparison_of_ARM_processors#ARMv8-A |
| 13 | + |
| 14 | +## Target maintainers |
| 15 | + |
| 16 | +* [Rust Embedded Devices Working Group Arm Team] |
| 17 | + |
| 18 | +[Rust Embedded Devices Working Group Arm Team]: https://github.com/rust-embedded/wg?tab=readme-ov-file#the-arm-team |
| 19 | + |
| 20 | +## Target CPU and Target Feature options |
| 21 | + |
| 22 | +It is possible to tell Rust (or LLVM) that you have a specific model of Arm |
| 23 | +processor, using the [`-Ctarget-cpu`][target-cpu] option. You can also control |
| 24 | +whether Rust (or LLVM) will include instructions that target optional hardware |
| 25 | +features, e.g. hardware floating-point, or Advanced SIMD operations, using |
| 26 | +[`-Ctarget-feature`][target-feature]. |
| 27 | + |
| 28 | +It is important to note that selecting a *target-cpu* will typically enable |
| 29 | +*all* the optional features available from Arm on that model of CPU and your |
| 30 | +particular implementation of that CPU may not have those features available. |
| 31 | +In that case, you can use `-Ctarget-feature=-option` to turn off the specific |
| 32 | +CPU features you do not have available, leaving you with the optimized |
| 33 | +instruction scheduling and support for the features you do have. More details |
| 34 | +are available in the detailed target-specific documentation. |
| 35 | + |
| 36 | +<div class="warning"> |
| 37 | + |
| 38 | +Many target-features are currently unstable and subject to change, and |
| 39 | +if you use them you should disassemble the compiler output and manually inspect |
| 40 | +it to ensure only appropriate instructions for your CPU have been generated. |
| 41 | + |
| 42 | +</div> |
| 43 | + |
| 44 | +If you wish to use the *target-cpu* and *target-feature* options, you can add |
| 45 | +them to your `.cargo/config.toml` file alongside any other flags your project |
| 46 | +uses (likely linker related ones): |
| 47 | + |
| 48 | +```toml |
| 49 | +rustflags = [ |
| 50 | + # Usual Arm bare-metal linker setup |
| 51 | + "-Clink-arg=-Tlink.x", |
| 52 | + "-Clink-arg=--nmagic", |
| 53 | + # tell Rust we have a Cortex-A72 |
| 54 | + "-Ctarget-cpu=cortex-a72", |
| 55 | +] |
| 56 | + |
| 57 | +[build] |
| 58 | +target = "aarch64-unknown-none" |
| 59 | +``` |
| 60 | + |
| 61 | +[target-cpu]: https://doc.rust-lang.org/rustc/codegen-options/index.html#target-cpu |
| 62 | +[target-feature]: https://doc.rust-lang.org/rustc/codegen-options/index.html#target-feature |
| 63 | + |
| 64 | +## Requirements |
| 65 | + |
| 66 | +These targets are cross-compiled and use static linking. |
| 67 | + |
| 68 | +By default, the `lld` linker included with Rust will be used; however, you may |
| 69 | +want to use the GNU linker instead. This can be obtained for Windows/Mac/Linux |
| 70 | +from the [Arm Developer Website][arm-gnu-toolchain], or possibly from your OS's |
| 71 | +package manager. To use it, add the following to your `.cargo/config.toml`: |
| 72 | + |
| 73 | +```toml |
| 74 | +[target.<your-target>] |
| 75 | +linker = "arm-none-eabi-ld" |
| 76 | +``` |
| 77 | + |
| 78 | +The GNU linker can also be used by specifying `aarch64-none-gcc` as the |
| 79 | +linker. This is needed when using GCC's link time optimization. |
| 80 | + |
| 81 | +These targets don't provide a linker script, so you'll need to bring your own |
| 82 | +according to the specific device you are using. Pass |
| 83 | +`-Clink-arg=-Tyour_script.ld` as a rustc argument to make the linker use |
| 84 | +`your_script.ld` during linking. |
| 85 | + |
| 86 | +All AArch64 processors include an FPU. The difference between the `-none` and |
| 87 | +`-none-softfloat` targets is whether the FPU is used for passing function arguments. |
| 88 | +You may prefer the `-softfloat` target when writing a kernel or interfacing with |
| 89 | +pre-compiled binaries that use the soft-float ABI. |
| 90 | + |
| 91 | +When using the hardfloat targets, the minimum floating-point features assumed |
| 92 | +are those of the `fp-armv8`, which excludes NEON SIMD support. If your |
| 93 | +processor supports a different set of floating-point features than the default |
| 94 | +expectations of `fp-armv8`, then these should also be enabled or disabled as |
| 95 | +needed with `-C target-feature=(+/-)`. For example, |
| 96 | +`-Ctarget-feature=+neon-fp-armv8`. |
| 97 | + |
| 98 | +[arm-gnu-toolchain]: https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain |
| 99 | + |
| 100 | +## Testing |
| 101 | + |
| 102 | +This is a cross-compiled target that you will need to emulate during testing. |
| 103 | + |
| 104 | +The exact emulator that you'll need depends on the specific device you want to |
| 105 | +run your code on. |
| 106 | + |
| 107 | +## Start-up and Low-Level Code |
| 108 | + |
| 109 | +The [Rust Embedded Devices Working Group Arm Team] maintain the |
| 110 | +[`aarch64-cpu`], which may be useful for writing bare-metal code using this |
| 111 | +target. |
| 112 | + |
| 113 | +The *TrustedFirmware* group also maintain [Rust crates for this |
| 114 | +target](https://github.com/ArmFirmwareCrates). |
| 115 | + |
| 116 | +[`aarch64-cpu`]: https://docs.rs/aarch64-cpu |
| 117 | + |
| 118 | +## Cross-compilation toolchains and C code |
| 119 | + |
| 120 | +This target supports C code compiled with the `aarch64-unknown-none` target |
| 121 | +triple and a suitable `-march` or `-mcpu` flag. |
0 commit comments