Rewrite SIMD article as "SIMD and Hardware Intrinsics"#54834
Merged
tannergooding merged 6 commits intoJul 20, 2026
Conversation
Modernize docs/standard/simd.md into a source-of-truth guide covering the layered SIMD support in .NET 11: System.Numerics fixed-shape types, Vector<T>, cross-platform Vector64/128/256/512, platform-specific hardware intrinsics, and TensorPrimitives. Adds a full common-operations reference, code-structure/remainder-handling guidance, an instruction-set configuration-knob reference, and testing/benchmarking sections, backed by a verified C# snippet project. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR modernizes the SIMD documentation by rewriting docs/standard/simd.md as “SIMD and Hardware Intrinsics”, expanding it to cover the full layered SIMD stack in modern .NET and backing the article with runnable snippet sources.
Changes:
- Rewrites and retitles the SIMD article to cover
System.Numerics,Vector<T>, fixed-widthVector64/128/256/512<T>, hardware intrinsics, andTensorPrimitives, including guidance on structure, remainder handling, testing, and benchmarking. - Adds a new
docs/standard/snippets/simd/csharp/snippet project with sample implementations used by the article. - Updates the fundamentals TOC entry to match the new article title.
Show a summary per file
| File | Description |
|---|---|
| docs/standard/simd.md | Major rewrite and retitle of the SIMD article; adds new guidance, reference tables, and snippet references. |
| docs/fundamentals/toc.yml | Updates the TOC display name to “SIMD and Hardware Intrinsics”. |
| docs/standard/snippets/simd/csharp/SimdSnippets.csproj | Adds the snippet project (net11.0) and references System.Numerics.Tensors. |
| docs/standard/snippets/simd/csharp/Program.cs | Adds a local verification runner for the snippet project. |
| docs/standard/snippets/simd/csharp/NumericsExamples.cs | Adds System.Numerics vector/matrix and Vector<T> examples referenced by the article. |
| docs/standard/snippets/simd/csharp/AdvancedVectorization.cs | Adds more advanced vectorization examples (width fan-out, masked remainder handling, jump-table remainder). |
| docs/standard/snippets/simd/csharp/SimpleVectorization.cs | Adds simpler vectorization examples (idempotent remainder handling, ASCII validation). |
| docs/standard/snippets/simd/csharp/HardwareIntrinsicsExample.cs | Adds a per-platform light-up example for hardware intrinsics with a portable fallback. |
| docs/standard/snippets/simd/csharp/TensorPrimitivesExample.cs | Adds TensorPrimitives span-math examples referenced by the article. |
Copilot's findings
- Files reviewed: 9/9 changed files
- Comments generated: 4
Escape the angle brackets in the Vector<T> heading (MD033 / OPS disallowed-html-tag) and drop a trailing space in the config-knob callout (MD009). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Match the EnableArm64Rdm/Rcpc knob names: RDM (Rounding Doubling Multiply Accumulate), not RDMA; and RCpc casing without the duplicated word. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The overlapping-tail load underflows for a non-empty buffer shorter than one vector; fall back to a scalar scan in that case so the sample is correct for any length. Verify small and empty buffers in the runner. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
gewarren
approved these changes
Jul 20, 2026
Sentence-case the title/heading/toc, drop redundant displayProperty=fullName from namespace xrefs, and take the copyedits from review (may->might, wording, and acronym spacing). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Member
Author
|
Thanks @gewarren -- applied all of these in 03d8f40: sentence-cased the title/H1/toc, dropped the redundant Note Reply posted by Copilot on my behalf. |
BillWagner
reviewed
Jul 20, 2026
BillWagner
left a comment
BillWagner
left a comment
Member
There was a problem hiding this comment.
There's one clarification that we need here.
Co-authored-by: Bill Wagner <wiwagn@microsoft.com>
BillWagner
approved these changes
Jul 20, 2026
This was referenced Jul 20, 2026
tannergooding
added a commit
to dotnet/runtime
that referenced
this pull request
Jul 21, 2026
) The general SIMD and hardware-intrinsics guidance now lives in the official docs, which were recently rewritten in dotnet/docs#54834. Our in-repo `docs/coding-guidelines/vectorization-guidelines.md` had become largely duplicative and out of sync, so this trims it down to defer to the official article and keep only the dotnet/runtime-specific nuance: - The `BoundedMemory` test helper for access-violation testing (with a repo-relative link and a short usage example). - The real `LastIndexOf` GC-hole case study (#73768 / fix #75857) behind the "prefer the element-offset overloads" rule. - The #64451 catalogue of real vectorized implementations to learn from. The lane-crossing worked example that the official rewrite dropped is being restored upstream in dotnet/docs#54840 rather than kept here, since it''s general teaching content and belongs where it stays in sync. ---------- Also adds a `vectorization` skill covering both authoring and reviewing SIMD code. Vectorization is a cross-cutting domain rather than a folder, so a task-triggered skill fits better than a file-scoped `.instructions.md`. The skill defers to the official docs and carries the same repo-specific nuance (prefer the span/`LoadUnsafe` element-offset overloads, `BoundedMemory` AV testing, the acceleration-toggle env vars, `char`/`bool` reinterpretation, and benchmarking before committing complexity), plus authoring/testing/review checklists. `copilot-instructions.md` gets a one-line nudge toward it, matching the existing `code-review`/`performance-benchmark` pattern. > [!NOTE] > This PR description was drafted by GitHub Copilot. --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Modernizes
docs/standard/simd.md, which was out of date and missing many of the SIMD/vectorization concepts that modern .NET exposes. Retitled to SIMD and Hardware Intrinsics (the official term) and updated its toc entry.The article now works through the layered SIMD support from highest to lowest level, aligned with the current dotnet/runtime vectorization guidance:
System.Numericsfixed-shape vector/matrix typesVector<T>(variable-width)Vector64/128/256/512<T>X86,Arm,Wasm)TensorPrimitivesfor ready-made vectorized span mathHighlights:
ConditionalSelectreasoning).EnableHWIntrinsic,MaxVectorTBitWidth,PreferredVectorBitWidth, and the per-groupingEnable*x86/x64 and Arm64 switches), with an explicit callout that these are diagnostic tools, that they don''t affect ReadyToRun/Native AOT or necessarily internal runtime routines, that enabling an unsupported knob is ignored, and that the set may differ across releases.Vector128<T>".All code snippets live in a new
docs/standard/snippets/simd/csharp/project (net11.0) and were built and run to verify output before inclusion.bin//obj/are gitignored and not part of the change.Note
This article and its snippets were drafted with AI assistance (
ai-usage: ai-assisted) and reviewed/verified against the runtime source and a compiled snippet project.Internal previews