Add documentation for the `target_feature` attribute by valentynkit · Pull Request #160218 · rust-lang/rust

valentynkit · 2026-07-30T13:42:12Z

Documents the target_feature attribute, aiming at the guide level and beginner friendly. Low level details and per-architecture feature table stay out in the Reference.

The example is wrapped in a hidden #[cfg(target_arch = "x86_64")] block to make the example compile everywhere the doctests run.

Part of #157604

r? @GuillaumeGomez

Tested with ./x test library/core --doc --test-args attribute_docs and the same for library/std.

GuillaumeGomez · 2026-07-30T20:08:56Z

I don't know too much about this attribute so I prefer letting someone else review it.

r? @RalfJung

rustbot · 2026-07-30T20:09:01Z

RalfJung is not on the review rotation at the moment.
They may take a while to respond.

RalfJung · 2026-07-31T06:36:22Z

The attribute is already documented in the Reference. Is it a good idea to duplicate that documentation here?

RalfJung

This seems correct from the opsem side but the writing needs work.

Unfortunately I don't have the time to shepherd this all the way through.
r? @workingjubilee

View changes since this review

RalfJung · 2026-07-31T06:32:23Z

+//
+/// Enables extra CPU instructions for a single function.
+///
+/// A program is compiled for a baseline CPU, so instructions that only newer CPUs support go


Where does the baseline come from?

RalfJung · 2026-07-31T06:35:59Z

+/// baseline. The `-C target-feature` and `-C target-cpu` compiler flags enable features for the
+/// whole crate instead, which raises the minimum CPU the binary runs on.


This is an oddly dangling remark without flow.

It seems better to first mention the -C flags, and then pivot from there to the per-function version. Also, -Ctarget-cpu is very different from -Ctarget-fature, so throwing them into one bag here is quite confusing. -Ctarget-feature and #[target_feature] are closely related, they work on the same set of features; that should be mentioned.

rustbot · 2026-07-31T06:37:07Z

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

RalfJung · 2026-07-31T06:41:02Z

Also, given the context in #160219, I would like to emphasize that in my view, we should not land AI-generated docs. I don't know if these docs were AI-generated, and this is just my opinion as the official policy banning AI-generated docs has not landed yet. But to inform my own judgment as a reviewer I'd like to know whether you wrote these docs entirely yourself or whether you edited a draft that was generated by AI. This is relevant because AI-generated text and code needs to be reviewed in a very different way than human-written text and code (because the kinds of mistakes AIs make are different from the mistakes humans make).

valentynkit · 2026-08-25T20:58:02Z

Also, given the context in #160219, I would like to emphasize that in my view, we should not land AI-generated docs.

Thanks for reviewing and highlighting what worth attention. The initial version of this PR was AI-generated, and I hadn't disclosed that, sorry for that, I've changed how I work on contributions since getting the feedback on AI usage, and follow LLM Policy.
This version I rewrote myself, from scratch and verified with what is documented in Reference.

As for the docs, I made it more guide focused, and beginner friendly, it's detailed so If you think anything should be cut out to not duplicate information from Reference, I could shrink it.

workingjubilee · 2026-08-25T21:20:39Z

Thanks for the update, I'll try to take a look soon.

Document the built-in `target_feature` attribute, using the `#[doc(attribute = "..."`)]

rustbot · 2026-10-05T13:52:53Z

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

rust-bors · 2026-10-19T07:13:51Z

☔ The latest upstream changes (presumably #164556) made this pull request unmergeable. Please resolve the merge conflicts by rebasing.

workingjubilee · 2026-10-30T21:44:16Z

Thanks for the update, I'll try to take a look soon.

Originally posted by @workingjubilee in #160218 (comment)

workingjubilee · 2026-10-30T21:08:46Z

+
+#[doc(attribute = "target_feature")]
+//
+/// Enables extra CPU instructions for a single function.


Hmm. It's an ISA extension... it doesn't necessarily correspond exactly to extra instructions. The actual behavior is thus effectively to specify to the code generator that a behavior of the CPU is different (with the baseline being, yes, "more instructions are valid encodings instead of being undefined or only-trapping").

A good example of a non-instruction feature would be ermsb, AKA "rep movs is good": https://github.com/llvm/llvm-project/blob/4f7ca43759f63102f3f73677a5008d0a5576ed12/llvm/lib/Target/X86/X86.td#L398

It changes nothing about what the CPU can do, but encourages the compiler to use a simpler code pattern in some cases.

And yes, it is on the list of officially supported features:

$ rustc --print target-features Features supported by rustc for this target: ... ermsb - REP MOVS/STOS are fast.

Unfortunately crt-static is also a target feature, but I don't think we need to even think about it as IMO it should not have been. It is a far more annoying counterexample and it doesn't interact with a number of things "real" features do.

View changes since the review

workingjubilee · 2026-10-30T21:14:23Z

+/// Calling a `#[target_feature]` function on a CPU that lacks the features is undefined
+/// behavior, unless the platform explicitly documents it to be safe. That is why the call
+/// needs `unsafe`: the caller must verify that the features are present. Even in a crate built
+/// with `-C target-feature=+avx2`, calling `increment_avx2` still needs `unsafe`; only a
+/// caller that enables the same features through its own `#[target_feature]` attribute may
+/// call it without.


Not "documents" here, but "defines". It needs to be a foundational promise. If it was okay today but may not be okay in the future, we couldn't rely on it, and vice versa, it needs to have been okay since the very start of the platform defined by the target. This is why wasm is allowed to be different, because invalid instructions must have a reliable behavior of being rejected, from the beginning of wasm onward.

Further, the feature doesn't need to just be physically available on the CPU. People must perform runtime detection instead of assuming a feature is enabled because e.g. the behavior is equally arbitrary if the OS refuses to enable the feature, from our perspective, though more typically it at least incurs an invalid instruction trap since the instruction does get parsed correctly.

...However, as noted by the Gracemont comment, this is not guaranteed, as a feature being disabled despite being physically available can be due to kernel software detecting a per-core ISA difference and thus refusing to enable it, and so using those instructions can still reach a hardware UB case even if some cores parse it correctly.

View changes since the review

I would invert this segment and start at the conclusion: Describe what is needed to be sound and correct, and then add the recursive exemption, and then add the wasm exemption (as that is the only platform that has such an exemption). Then -Ctarget-feature doesn't even come up because we are only describing what you must do. It's a red herring.

workingjubilee · 2026-10-30T21:20:22Z

+/// The value of `enable` is one or more comma-separated feature names, and the names are
+/// architecture-specific: `avx2` belongs to x86, `neon` to ARM. The `-C target-feature` flag


This feels vague to me between "each architecture has a set of names and those names are not assigned to other architectures" and "each name has a specific meaning for each architecture". It's the latter. They are not required to match to a single feature on a single architecture. Many platforms have aes, for example, which indicates the same computation but may have some variance in its implementation details. Also, we can have the same name mean fully different things based on architecture.

View changes since the review

workingjubilee · 2026-10-30T21:33:59Z

+/// Newer CPUs support instructions that older ones may lack. AVX2, for example, processes 32
+/// bytes in a single instruction, but a program using it everywhere cannot run on older machines.


Mmm. The CPUs that shipped with AVX2 were in 2011. They are quite old by now.

The difference is that Intel kept shipping new lines of non-AVX2 CPUs also until... oh, into the 2020s. Tremont misses AVX2. https://en.wikipedia.org/wiki/Tremont_(microarchitecture)

Gracemont has it, but missed AVX512, and that's why Alder Lake wound up not supporting AVX512 except for a few early CPUs that hadn't had it fused off yet. The motherboard is still supposed to disable their AVX512 though, so there's no per-core variance in instruction set.

View changes since the review

It would probably be better to say something like "early or low-power x86-64 CPUs", I think.

workingjubilee · 2026-10-30T21:41:10Z

+/// needs `unsafe`: the caller must verify that the features are present. Even in a crate built
+/// with `-C target-feature=+avx2`, calling `increment_avx2` still needs `unsafe`; only a
+/// caller that enables the same features through its own `#[target_feature]` attribute may
+/// call it without.


I believe this part is a fairly arbitrary decision by us so that whether a crate passes unsafety-checking doesn't depend on your specific -Ctarget-feature flags, it has less to do with soundness per se and more to do with making the compiler easy to wield.

View changes since the review

workingjubilee · 2026-10-30T21:47:16Z

+/// caller that enables the same features through its own `#[target_feature]` attribute may
+/// call it without.
+///
+/// The value of `enable` is one or more comma-separated feature names, and the names are


We should probably show what this looks like.

View changes since the review

workingjubilee · 2026-10-30T21:56:23Z

+/// The value of `enable` is one or more comma-separated feature names, and the names are
+/// architecture-specific: `avx2` belongs to x86, `neon` to ARM. The `-C target-feature` flag
+/// accepts the same names crate-wide, and run-time detection has per-architecture macros such
+/// as [`is_x86_feature_detected`] and [`is_aarch64_feature_detected`], which callers use to
+/// confirm the running CPU has a feature before the call.


It feels like this leaves slightly vague something that it should probably explicate: the same strings work for both.

In fact, we should probably move this way up, to near the start, and maybe reference rustc --print target-features?

View changes since the review

rustbot · 2026-10-30T21:58:12Z

Reminder, once the PR becomes ready for a review, use @rustbot ready.

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jul 30, 2026

rustbot assigned GuillaumeGomez Jul 30, 2026

rustbot added the T-libs Relevant to the library team, which will review and decide on the PR/issue. label Jul 30, 2026

rustbot assigned RalfJung and unassigned GuillaumeGomez Jul 30, 2026

RalfJung reviewed Jul 31, 2026

View reviewed changes

rustbot assigned workingjubilee and unassigned RalfJung Jul 31, 2026

This comment has been minimized.

Sign in to view

valentynkit force-pushed the docs-target-feature-attribute branch from 507f37d to 93b83d9 Compare August 25, 2026 20:41

This comment has been minimized.

Sign in to view

fmease mentioned this pull request Sep 20, 2026

Tracking issue for documenting individual built-in inert attributes in the standard library using #[doc(attribute = "…")] #157604

Open

21 of 80 tasks

This comment has been minimized.

Sign in to view

Add documentation for the target_feature attribute

a8ebb3a

Document the built-in `target_feature` attribute, using the `#[doc(attribute = "..."`)]

valentynkit force-pushed the docs-target-feature-attribute branch from 93b83d9 to a8ebb3a Compare October 5, 2026 13:52

workingjubilee requested changes Oct 30, 2026

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 Oct 30, 2026

		/// baseline. The `-C target-feature` and `-C target-cpu` compiler flags enable features for the
		/// whole crate instead, which raises the minimum CPU the binary runs on.

		/// The value of `enable` is one or more comma-separated feature names, and the names are
		/// architecture-specific: `avx2` belongs to x86, `neon` to ARM. The `-C target-feature` flag

		/// Newer CPUs support instructions that older ones may lack. AVX2, for example, processes 32
		/// bytes in a single instruction, but a program using it everywhere cannot run on older machines.

Conversation

valentynkit commented Jul 30, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

GuillaumeGomez commented Jul 30, 2026

Uh oh!

rustbot commented Jul 30, 2026

Uh oh!

RalfJung commented Jul 31, 2026

Uh oh!

RalfJung 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!

RalfJung Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

RalfJung Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

rustbot commented Jul 31, 2026

Uh oh!

RalfJung commented Jul 31, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

valentynkit commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

workingjubilee commented Aug 25, 2026

Uh oh!

This comment has been minimized.

rustbot commented Oct 5, 2026

Uh oh!

rust-bors Bot commented Oct 19, 2026

Uh oh!

workingjubilee commented Oct 30, 2026

Uh oh!

workingjubilee Oct 30, 2026 • 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!

workingjubilee Oct 30, 2026 • 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!

workingjubilee Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

workingjubilee Oct 30, 2026 • 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!

workingjubilee Oct 30, 2026 • 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!

workingjubilee Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

workingjubilee Oct 30, 2026 • 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!

workingjubilee Oct 30, 2026 • 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!

workingjubilee Oct 30, 2026 • 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!

rustbot commented Oct 30, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

valentynkit commented Jul 30, 2026 •

edited by rustbot

Loading

RalfJung left a comment •

edited by rustbot

Loading

valentynkit commented Aug 25, 2026 •

edited

Loading

workingjubilee Oct 30, 2026 •

edited by rustbot

Loading

workingjubilee Oct 30, 2026 •

edited by rustbot

Loading

workingjubilee Oct 30, 2026 •

edited by rustbot

Loading

workingjubilee Oct 30, 2026 •

edited by rustbot

Loading

workingjubilee Oct 30, 2026 •

edited by rustbot

Loading

workingjubilee Oct 30, 2026 •

edited by rustbot

Loading

workingjubilee Oct 30, 2026 •

edited by rustbot

Loading