Arm bare-metal target doc changes

[jonathanpallant]

Updates the Arm bare-metal target docs:

• Detailed pages for all the Cortex-M targets, including details about setting target-cpu and target-features to suit specific Arm models
• More detail about the difference between eabi and eabihf
• Marks the Embedded Devices Working Group Cortex-M Team as the maintainer of the Cortex-M targets

[rustbot]

r? @ehuss

rustbot has assigned @ehuss.
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

[rustbot]

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

cc @Nilstrieb

[Noratrieb]

I do not know enough about ARM to comment whether the content is correct, but you do as a target maintainer so I trust you there.

@bors r+ rollup

[bors]

📌 Commit b173984 has been approved by Nilstrieb

It is now in the queue for this repository.

[Noratrieb]

@bors r- nevermind

[thejpster]

What went wrong?

[Noratrieb]

linkcheck #124404 (comment)

[thejpster]

Yeah I saw that and I don't know what I did wrong.

I added src/doc/rustc/src/platform-support/thumbv6m-none-eabi.md, and I linked to it. Do I need to tell it about the new file? Or is there a typo I just can't see?

[ehuss]

New files need to be added to SUMMARY.md.

[chrisnc]

Left a few minor notes. At a higher level though, would it be best to consolidate the hf and non-hf documents for the variants that have both? There's a lot of duplicated information that would have to be manually kept in sync as-is.

[jonathanpallant]

Left a few minor notes. At a higher level though, would it be best to consolidate the hf and non-hf documents for the variants that have both? There's a lot of duplicated information that would have to be manually kept in sync as-is.

I've done this in the most recent commit. If we don't like it, I can drop it.

[chrisnc]

Arm consistently uses title case for their own name and architecture names ("Armv6-M", "Armv7E-M", etc.) in their docs these days, so probably should do that here. Right now it's a mix.

[jonathanpallant]

Arm consistently uses title case for their own name and architecture names ("Armv6-M", "Armv7E-M", etc.) in their docs these days, so probably should do that here. Right now it's a mix.

Oof. OK, I've done it. But I'm not sure I like how Arm spell it.

Also, I didn't touch "ARM64" (which is a Microsoft term, not an Arm term).

[chrisnc]

Arm

[chrisnc]

Looks great! I will try and assemble similar tables for the Cortex-R's in the next week or so.

[jonathanpallant]

Ok one more update done - I added a section clarifying the terms Arm ISA, Thumb ISA, Thumb-2 ISA, A32 and T32.

[ehuss]

Thanks!

@bors r=chrisnc rollup

[bors]

📌 Commit fcaba9c has been approved by chrisnc

It is now in the queue for this repository.

[bors]

⌛ Testing commit fcaba9c with merge cfb2410...

[bors]

☀️ Test successful - checks-actions
Approved by: chrisnc
Pushing cfb2410 to master...

[rust-timer]

Finished benchmarking commit (cfb2410): comparison URL.

Overall result: no relevant changes - no action needed

@rustbot label: -perf-regression

Instruction count

This benchmark run did not return any relevant results for this metric.

Max RSS (memory usage)

This benchmark run did not return any relevant results for this metric.

Cycles

This benchmark run did not return any relevant results for this metric.

Binary size

This benchmark run did not return any relevant results for this metric.

Bootstrap: 676.596s -> 674.001s (-0.38%)
Artifact size: 315.96 MiB -> 315.98 MiB (0.01%)

[RalfJung]

FWIW this is a problematic piece of advice to give, since this target feature is also implicated in the soundness issue tracked at #116344.

[thejpster]

Although as we discussed extensively on Zulip currently we know of no other way of stopping target-cpu=cortex-m7 (or similar) from emitting FPU instructions like vadd.f32, yet it's reasonable to want the Cortex-M7 specific instruction scheduling optimisations even if your Cortex-M7 doesn't have an FPU.

This feature is totally unsound on *-unknown-none-eabihf, but it's both sound and useful on *-unknown-none-eabi. The 'target-feature' checker can currently only look at the target-architecture, and not the full target triple, so it's unclear where we go from here.

[RalfJung]

The target-feature checker is still WIP, and will be improved to handle this, somehow.

But the docs maybe should call out that this same flag is unsound to use on other targets (until rustc reaches the point where it is able to tell users about this directly).

[RalfJung]

Also, it is rather unusual for stable docs to recommend unstable/unsupported features. Using these flags will cause warnings on current compilers! (And the only reason those warnings are not hard errors is that target features are a terrible mess and we are grandfathering in all LLVM features, and hoping that doesn't break too many things.)

[RalfJung]

Also, it is rather unusual for stable docs to recommend unstable/unsupported features. Using these flags will cause warnings on current compilers! (And the only reason those warnings are not hard errors is that target features are a terrible mess and we are grandfathering in all LLVM features, and hoping that doesn't break too many things.)

We have an issue for this now: #130988