Update the arm-* and aarch64-* platform docs. #146419

thejpster · 2025-09-10T18:31:19Z

This PR updates some of the arm*-unknown-none target docs, and adds some missing target pages.

aarch64-none-elf and aarch64-none-elf-softfloat

The Rust Embedded Devices Working Group's Arm Team is added as a maintainer, and a target page is added. Links are added to the EDWG's support crates for this target.

armv7a-none-eabi and armv7a-none-eabihf

The Rust Embedded Devices Working Group's Arm Team is added as a maintainer, and a target page is added. Links are added to the EDWG's support crates for this target.

armv7r-none-eabi and armv7r-none-eabihf

The Rust Embedded Devices Working Group's Arm Team is added as a maintainer, and the target page is split from the Big Endian versions. Links are added to the EDWG's support crates for this target.

armebv7r-none-eabi and armveb7r-none-eabihf

The target page is split from the Little Endian versions. No change in maintainers.

I have agreement to add EDWG/T-Arm as maintainers, which was voted upon in their repo.

rustbot · 2025-09-10T18:31:23Z

Some changes occurred in src/doc/rustc/src/platform-support

cc @Noratrieb

rustbot · 2025-09-10T18:31:25Z

r? @lcnr

rustbot has assigned @lcnr.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

The Rust Embedded Devices Working Group (wg-embedded) Arm Team (t-arm) agreed to listed as maintainers of: * aarch64-unknown-none * aarch64-unknown-none-softfloat * armv7a-none-eabi * armv7r-none-eabi * armv7r-none-eabihf The aarch64-unknown-none* target didn't have a page so I added it. wg-embedded t-arm did not want to take over: * armebv7r-none-eabi * armebv7r-none-eabihf So I gave them their own target page. The current maintainer remains.

thejpster · 2025-09-10T18:52:36Z

Force-pushed with fixed markdown formatting.

src/doc/rustc/src/platform-support/armv7a-none-eabi.md

From #1.

src/doc/rustc/src/platform-support/aarch64-unknown-none.md

lcnr · 2025-09-11T10:11:43Z

r? @workingjubilee maybe?

rustbot · 2025-09-11T10:11:47Z

workingjubilee is currently at their maximum review capacity.
They may take a while to respond.

workingjubilee

I may find more nits but the maintainer assent one is blocking, I think.

View changes since this review

workingjubilee · 2025-09-11T20:21:28Z

src/doc/rustc/src/platform-support/aarch64-unknown-none.md

+## Start-up and Low-Level Code
+
+The [Rust Embedded Devices Working Group Arm Team] maintain the
+[`aarch64-cpu`], which may be useful for writing bare-metal code using this


the aarch64-cpu... what?

I think you mean "crate", or you mean to delete the "the" from the previous line.

oops. Fixed.

workingjubilee · 2025-09-11T20:22:48Z

src/doc/rustc/src/platform-support/aarch64-unknown-none.md

+
+```toml
+[target.<your-target>]
+linker = "arm-none-eabi-ld"


This does not seem to be the right linker name for aarch64 targets?

Correct. Fixed.

workingjubilee · 2025-09-11T20:28:01Z

src/doc/rustc/src/platform-support/aarch64-unknown-none.md

+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=(+/-)`. For example,
+`-Ctarget-feature=+neon-fp-armv8`.


Doesn't this need a comma?

Suggested change

`-Ctarget-feature=+neon-fp-armv8`.

`-Ctarget-feature=+neon,-fp-armv8`.

Fair point. I'll remove the example, as I don't think it's actually helpful.

workingjubilee · 2025-09-11T20:44:38Z

src/doc/rustc/src/platform-support/armebv7r-none-eabi.md

+
+## Target maintainers
+
+* [@chrisnc](https://github.com/chrisnc)


Uhm. Hrm.

@chrisnc Do you assent?

@thejpster I am not sure I have seen an assent by Chris to maintain this specific target variant.

The armebv7r and armv7r targets were on the same page, and so I concluded Chris was the maintainer for both. Pretty sure he wrote the page back in 90893e4.

https://doc.rust-lang.org/beta/rustc/platform-support/armv7r-none-eabi.html

The format for these was updated a while ago to drop the bullet points for ease of copy-pasting the usernames in GitHub issues and PRs. Please drop those, no matter who's being listed here (and in all the other files) :)

Gelbpunkt

I only looked at the aarch64 document since that's what I'm most familiar with, most of my comments should also apply to the other documents from what I can tell. I'm very happy about more extensive documentation, this is a fairly good first step.

View changes since this review

Gelbpunkt · 2025-09-12T08:24:20Z

src/doc/rustc/src/platform-support/aarch64-unknown-none.md

+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",
+]


I'm personally not a fan of having such very general compiler flags documented or explained in target-specific documentation. It makes a lot of sense to show an example of using a linker script, since this is a bare-metal target, but target-cpu/target-feature really isn't specific to this family of targets and I'm not a fan of encouraging duplicating this across all the target documentation.

Is it documented anywhere else? If so, we can do a PR to remove it from all the target pages.

Removed surplus text from aarch64-unknown-none.md.

Gelbpunkt · 2025-09-12T08:27:02Z

src/doc/rustc/src/platform-support/aarch64-unknown-none.md

+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=(+/-)`.


Calling convention explanation (i.e. difference between -softfloat and the other target and ideally a link to AAPCS64) should probably go in a separate section rather than "Requirements".

Moved this text to the section above.

Gelbpunkt · 2025-09-12T08:28:24Z

src/doc/rustc/src/platform-support/aarch64-unknown-none.md

+## 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.


AFAIK the testing section in the target support documentation is usually about running the tests for the compiler itself, which isn't supported for these targets.

Removed the section. It wasn't useful.

Gelbpunkt · 2025-09-12T08:31:04Z

src/doc/rustc/src/platform-support/aarch64-unknown-none.md

+## 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


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.

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.

Gelbpunkt · 2025-09-12T08:32:19Z

src/doc/rustc/src/platform-support/armebv7r-none-eabi.md

+
+## Target maintainers
+
+* [@chrisnc](https://github.com/chrisnc)


The format for these was updated a while ago to drop the bullet points for ease of copy-pasting the usernames in GitHub issues and PRs. Please drop those, no matter who's being listed here (and in all the other files) :)

…-metal targets

thejpster · 2025-09-12T19:28:06Z

The format for these was updated a while ago to drop the bullet points for ease of copy-pasting the usernames in GitHub issues and PRs

It seems the existing target docs were not updated when this rule came in. I'm removed the bullets for all the targets maintained by the Rust Embedded Devices Working Group's Arm Team as requested.

Removes a bunch of information that isn't, strictly speaking, target specific.

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Sep 10, 2025

rustbot assigned lcnr Sep 10, 2025

This comment has been minimized.

Sign in to view

thejpster force-pushed the update-arm-target-docs branch from 8a54175 to faf0e14 Compare September 10, 2025 18:51

fbstj reviewed Sep 10, 2025

View reviewed changes

src/doc/rustc/src/platform-support/armv7a-none-eabi.md Outdated Show resolved Hide resolved

This comment has been minimized.

Sign in to view

Pick up changes from robamu that I missed.

f1abb70

From #1.

thejpster force-pushed the update-arm-target-docs branch from 827e2cd to f1abb70 Compare September 10, 2025 19:31

This comment has been minimized.

Sign in to view

workingjubilee requested changes Sep 10, 2025

View reviewed changes

src/doc/rustc/src/platform-support/aarch64-unknown-none.md Show resolved Hide resolved

src/doc/rustc/src/platform-support/aarch64-unknown-none.md Show resolved Hide resolved

thejpster added 3 commits September 10, 2025 23:36

Add missing links in platform-support.md

3d3769a

Add aarch64-unknown-none to SUMMARY.md

5a74222

Update aarch64-unknown-none.md to include -softfloat too

409a1fb

rustbot assigned workingjubilee and unassigned lcnr Sep 11, 2025

workingjubilee requested changes Sep 11, 2025

View reviewed changes

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 11, 2025

thejpster added 2 commits September 11, 2025 22:04

Cleanups from review comments.

1621ce6

Insert missing word.

a0d1f5a

Gelbpunkt suggested changes Sep 12, 2025

View reviewed changes

Remove bullet points from the target maintainer list for the arm bare…

4383a4f

…-metal targets

Re-order and re-work the aarch64-unknown-none platform support page.

ea661e9

Removes a bunch of information that isn't, strictly speaking, target specific.

	`-Ctarget-feature=+neon-fp-armv8`.
	`-Ctarget-feature=+neon,-fp-armv8`.


		## Target maintainers

		* [@chrisnc](https://github.com/chrisnc)

Update the arm-* and aarch64-* platform docs. #146419

Are you sure you want to change the base?

Update the arm-* and aarch64-* platform docs. #146419

Conversation

thejpster commented Sep 10, 2025

aarch64-none-elf and aarch64-none-elf-softfloat

armv7a-none-eabi and armv7a-none-eabihf

armv7r-none-eabi and armv7r-none-eabihf

armebv7r-none-eabi and armveb7r-none-eabihf

Uh oh!

rustbot commented Sep 10, 2025

Uh oh!

rustbot commented Sep 10, 2025

Uh oh!

This comment has been minimized.

This comment has been minimized.

thejpster commented Sep 10, 2025

Uh oh!

Uh oh!

This comment has been minimized.

This comment has been minimized.

Uh oh!

Uh oh!

lcnr commented Sep 11, 2025

Uh oh!

rustbot commented Sep 11, 2025

Uh oh!

workingjubilee left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Gelbpunkt left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Gelbpunkt Sep 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thejpster commented Sep 12, 2025

Uh oh!

Uh oh!

workingjubilee left a comment •

edited

Loading

Gelbpunkt left a comment •

edited by rustbot

Loading

Gelbpunkt Sep 12, 2025 •

edited

Loading