11# ` {arm,thumb}*-none-eabi(hf)? `
22
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- - [ armv8r-none-eabihf] ( armv8r-none-eabihf.md )
17-
18- Bare-metal target for 32-bit ARM CPUs.
19-
20- If a target has a ` *hf ` variant, that variant uses the hardware floating-point
21- ABI and enables some minimum set of floating-point features based on the FPU(s)
22- available in that processor family.
3+ ## Tier 2 Target List
4+
5+ - Arm A-Profile Architectures
6+ - ` armv7a-none-eabi `
7+ - Arm R-Profile Architectures
8+ - [ ` armv7r-none-eabi ` and ` armv7r-none-eabihf ` ] ( armv7r-none-eabi.md )
9+ - [ ` armebv7r-none-eabi ` and ` armebv7r-none-eabihf ` ] ( armv7r-none-eabi.md )
10+ - Arm M-Profile Architectures
11+ - [ ` thumbv6m-none-eabi ` ] ( thumbv6m-none-eabi.md )
12+ - [ ` thumbv7m-none-eabi ` ] ( thumbv7m-none-eabi.md )
13+ - [ ` thumbv7em-none-eabi ` ] ( thumbv7em-none-eabi.md ) and [ ` thumbv7em-none-eabihf ` ] ( thumbv7em-none-eabihf.md )
14+ - [ ` thumbv8m.base-none-eabi ` ] ( thumbv8m.base-none-eabi.md )
15+ - [ ` thumbv8m.main-none-eabi ` ] ( thumbv8m.main-none-eabi.md ) and [ ` thumbv8m.main-none-eabihf ` ] ( thumbv8m.main-none-eabihf.md )
16+ - * Legacy* Arm Architectures
17+ - None
18+
19+ ## Tier 3 Target List
20+
21+ - Arm A-Profile Architectures
22+ - ` armv7a-none-eabihf `
23+ - Arm R-Profile Architectures
24+ - [ ` armv8r-none-eabihf ` ] ( armv8r-none-eabihf.md )
25+ - Arm M-Profile Architectures
26+ - None
27+ - * Legacy* Arm Architectures
28+ - [ ` armv4t-none-eabi ` and ` thumbv4t-none-eabi ` ] ( armv4t-none-eabi.md )
29+ - [ ` armv5te-none-eabi ` and ` thumbv5te-none-eabi ` ] ( armv5te-none-eabi.md )
30+
31+ ## Common Target Details
32+
33+ This documentation covers details that apply to a range of bare-metal target for
34+ 32-bit ARM CPUs. In addition, target specific details may be covered in their
35+ own document.
36+
37+ If a target ends in ` eabi ` , that target uses the so-called * soft-float ABI* :
38+ functions which take ` f32 ` or ` f64 ` as arguments will have those values packed
39+ into integer registers. This means that an FPU is not required from an ABI
40+ perspective, but within a function FPU instructions may still be used if the
41+ code is compiled with a ` target-cpu ` or ` target-feature ` option that enables
42+ FPU support.
43+
44+ If a target ends if ` eabihf ` , that target uses the so-called * hard-float ABI* :
45+ functions which take ` f32 ` or ` f64 ` as arguments will have them passed via FPU
46+ registers. These target therefore require the use of an FPU and will assume the
47+ minimum support FPU for that architecture is available. More advanced FPU
48+ instructions (e.g. ones that work on double-precision ` f64 ` values) may be
49+ generated if the code is compiled with a ` target-cpu ` or ` target-feature ` option
50+ that enables such additional FPU support.
51+
52+ ## Target CPU and Target Feature options
53+
54+ It is possible to tell Rust (or LLVM) that you have a specific model of Arm
55+ processor, using the [ ` -C target-cpu ` ] [ target-cpu ] option. You can also control
56+ whether Rust (or LLVM) will include instructions that target optional hardware
57+ features, e.g. hardware floating point, or vector maths operations, using [ `-C
58+ target-feature`] [ target-feature ] .
59+
60+ It is important to note that selecting a * target-cpu* will typically enable
61+ * all* the optional features available from Arm on that model of CPU and your
62+ particular implementation of that CPU may not have those features available. In
63+ that case, you can use ` -C target-feature=-option ` to turn off the specific CPU
64+ features you do not have available, leaving you with the optimised instruction
65+ scheduling and support for the features you do have. More details are available
66+ in the detailed target-specific documentation.
67+
68+ ** Note:** Many target-features are currently unstable and subject to change, and
69+ if you use them you should dissassmble the compiler output and manually inspect
70+ it to ensure only appropriate instructions for your CPU have been generated.
71+
72+ If do you wish to use the * target-cpu* and * target-feature* options, you can add
73+ them to your ` .cargo/config.toml ` file alongside any other flags your project
74+ uses (likely linker related ones):
75+
76+ ``` toml
77+ rustflags = [
78+ # Usual Arm bare-metal linker setup
79+ " -C" " link-arg=-Tlink.x"
80+ " -C" " link-arg=--nmagic"
81+ # tell Rust we have a Cortex-M55
82+ " -C" " target-cpu=cortex-m55"
83+ # tell Rust our Cortex-M55 doesn't have Floating-Point M-Profile Vector
84+ # Extensions (but it does have everything else a Cortex-M55 could have).
85+ " -C" " target-feature=-mve.fp"
86+ ]
87+
88+ [build ]
89+ target = " thumbv8m.main-none-eabihf"
90+ ```
91+
92+ [ target-cpu ] : https://doc.rust-lang.org/rustc/codegen-options/index.html#target-cpu
93+ [ target-feature ] : https://doc.rust-lang.org/rustc/codegen-options/index.html#target-feature
2394
2495## Requirements
2596
@@ -45,14 +116,15 @@ according to the specific device you are using. Pass
45116` -Clink-arg=-Tyour_script.ld ` as a rustc argument to make the linker use
46117` your_script.ld ` during linking.
47118
48- Targets named ` thumb* ` instead of ` arm* `
49- generate Thumb-mode code by default. M-profile processors (` thumbv*m*-* `
50- targets) only support Thumb-mode code.
51- For the ` arm* ` targets, Thumb-mode code generation can be enabled by using
52- ` -C target-feature=+thumb-mode ` . Using the unstable
53- ` #![feature(arm_target_feature)] ` , the attribute
54- ` #[target_feature(enable = "thumb-mode")] ` can be applied to individual
55- ` unsafe ` functions to cause those functions to be compiled to Thumb-mode code.
119+ Targets named ` thumb* ` instead of ` arm* ` generate Thumb (T32) code by default
120+ instead of Arm (A32) code. Most Arm chips support both Thumb mode and Arm mode,
121+ except that M-profile processors (` thumbv*m*-* ` targets) only support Thumb-mode.
122+
123+ For the ` arm* ` targets, Thumb-mode code generation can be enabled by using `-C
124+ target-feature=+thumb-mode`. Using the unstable
125+ ` #![feature(arm_target_feature)] ` , the attribute `#[ target_feature(enable =
126+ "thumb-mode")] ` can be applied to individual ` unsafe` functions to cause those
127+ functions to be compiled to Thumb-mode code.
56128
57129## Building Rust Programs
58130
@@ -69,16 +141,27 @@ build-std = ["core"]
69141```
70142
71143Most of ` core ` should work as expected, with the following notes:
72- * If the target is not ` *hf ` , then floating-point operations are emulated in
73- software.
144+
145+ * Floating-point operations are emulated in software unless LLVM is told to
146+ enable FPU support (either by using an ` eabihf ` target, specifying a
147+ ` target-cpu ` with FPU support, or using a ` target-feature ` to support for a
148+ specific kind of FPU)
74149* Integer division is also emulated in software on some targets, depending on
75- the CPU.
76- * Architectures prior to ARMv7 don't have atomic instructions.
150+ the target, ` target-cpu ` and ` target-feature ` s.
151+ * Older Arm architectures (e.g. Armv4, Armv5TE and Armv6-M) are limited to basic
152+ [ ` load ` ] [ atomic-load ] and [ ` store ` ] [ atomic-store ] operations, and not more
153+ advanced operations like [ ` fetch_add ` ] [ fetch-add ] or
154+ [ ` compare_exchange ` ] [ compare-exchange ] .
77155
78156` alloc ` is also supported, as long as you provide your own global allocator.
79157
80158Rust programs are output as ELF files.
81159
160+ [ atomic-load ] : https://doc.rust-lang.org/stable/std/sync/atomic/struct.AtomicU32.html#method.load
161+ [ atomic-store ] : https://doc.rust-lang.org/stable/std/sync/atomic/struct.AtomicU32.html#method.store
162+ [ fetch-add ] : https://doc.rust-lang.org/stable/std/sync/atomic/struct.AtomicU32.html#method.fetch_add
163+ [ compare-exchange ] : https://doc.rust-lang.org/stable/std/sync/atomic/struct.AtomicU32.html#method.compare_exchange
164+
82165## Testing
83166
84167This is a cross-compiled target that you will need to emulate during testing.
0 commit comments