Skip to content

Commit 9cf1d26

Browse files
Copilotgewarren
Copilot
and
gewarren
committed
Add breaking change documentation for Arm64 SVE NonFaulting loads mask parameter
Co-authored-by: gewarren <[email protected]>
1 parent 66c4bbb commit 9cf1d26

File tree

3 files changed

+87
-0
lines changed

3 files changed

+87
-0
lines changed

‎docs/core/compatibility/10.0.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
3535
| Title | Type of change | Introduced version |
3636
|-------|-------------------|--------------------|
3737
| [ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change](core-libraries/10.0/activity-sampling.md) | Behavioral change | Preview 1 |
38+
| [Arm64 SVE NonFaulting loads require mask parameter](core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md) | Binary/source incompatible | Preview 1 |
3839
| [C# 14 overload resolution with span parameters](core-libraries/10.0/csharp-overload-resolution.md) | Behavioral change | Preview 1 |
3940
| [Consistent shift behavior in generic math](core-libraries/10.0/generic-math.md) | Behavioral change | Preview 1 |
4041
| [Default trace context propagator updated to W3C standard](core-libraries/10.0/default-trace-context-propagator.md) | Behavioral change | Preview 4 |

‎docs/core/compatibility/core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
title: "Breaking change: Arm64 SVE NonFaulting loads require mask parameter"
3+
description: "Learn about the breaking change in .NET 10 where Arm64 SVE NonFaulting load APIs now require a mask parameter as the first argument."
4+
ms.date: 01/31/2025
5+
ai-usage: ai-assisted
6+
ms.custom: https://github.com/dotnet/docs/issues/47439
7+
---
8+
9+
# Arm64 SVE NonFaulting loads require mask parameter
10+
11+
All Arm64 SVE NonFaulting load APIs have been updated to include a `mask` argument as the first position. This affects all methods with "NonFaulting" in their name in the <xref:System.Runtime.Intrinsics.Arm.Sve?displayProperty=fullName> class.
12+
13+
## Version introduced
14+
15+
.NET 10
16+
17+
## Previous behavior
18+
19+
NonFaulting load APIs took only an address parameter and would load a full vector:
20+
21+
```csharp
22+
// .NET 9 behavior
23+
Vector<short> result = Sve.LoadVectorByteNonFaultingZeroExtendToInt16(address);
24+
25+
// To do masked loading, you had to use ConditionalSelect
26+
Vector<short> maskedResult = Sve.ConditionalSelect(mask,
27+
Sve.LoadVectorByteNonFaultingZeroExtendToInt16(address),
28+
zero);
29+
```
30+
31+
## New behavior
32+
33+
NonFaulting load APIs now require a mask parameter as the first argument:
34+
35+
```csharp
36+
// .NET 10 behavior - mask parameter required
37+
Vector<short> result = Sve.LoadVectorByteNonFaultingZeroExtendToInt16(
38+
Sve.CreateTrueMaskInt16(), address);
39+
40+
// Masked loading is now done directly
41+
Vector<short> maskedResult = Sve.LoadVectorByteNonFaultingZeroExtendToInt16(
42+
mask, address);
43+
```
44+
45+
## Type of breaking change
46+
47+
This change can affect [binary compatibility](../../categories.md#binary-compatibility) and [source compatibility](../../categories.md#source-compatibility).
48+
49+
## Reason for change
50+
51+
This change was necessary because a non-faulting load updates the FFR (First Fault Register) depending on which vector lanes are loaded. The standard conversion of `ConditionalSelect(mask, LoadVectorNonFaulting(addr), zero)` to a masked load cannot be used because it doesn't properly handle the FFR register state. Therefore, the only valid way to implement a masked non-faulting load is by exposing it as a dedicated API with a mask parameter.
52+
53+
## Recommended action
54+
55+
- For existing uses of `Sve.ConditionalSelect(mask, Sve.LoadVector*NonFaulting*(addr), zero)`, replace them with `Sve.LoadVector*NonFaulting*(mask, addr)`.
56+
- For other uses of non-faulting loads that should load all elements, update them to include a true mask: `Sve.LoadVector*NonFaulting*(Sve.CreateTrueMask*(), addr)`.
57+
58+
## Affected APIs
59+
60+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorByteNonFaultingZeroExtendToInt16%2A?displayProperty=fullName>
61+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorByteNonFaultingZeroExtendToInt32%2A?displayProperty=fullName>
62+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorByteNonFaultingZeroExtendToInt64%2A?displayProperty=fullName>
63+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorByteNonFaultingZeroExtendToUInt16%2A?displayProperty=fullName>
64+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorByteNonFaultingZeroExtendToUInt32%2A?displayProperty=fullName>
65+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorByteNonFaultingZeroExtendToUInt64%2A?displayProperty=fullName>
66+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorInt16NonFaultingSignExtendToInt32%2A?displayProperty=fullName>
67+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorInt16NonFaultingSignExtendToInt64%2A?displayProperty=fullName>
68+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorInt16NonFaultingSignExtendToUInt32%2A?displayProperty=fullName>
69+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorInt16NonFaultingSignExtendToUInt64%2A?displayProperty=fullName>
70+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorInt32NonFaultingSignExtendToInt64%2A?displayProperty=fullName>
71+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorInt32NonFaultingSignExtendToUInt64%2A?displayProperty=fullName>
72+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorNonFaulting%2A?displayProperty=fullName>
73+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorSByteNonFaultingSignExtendToInt16%2A?displayProperty=fullName>
74+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorSByteNonFaultingSignExtendToInt32%2A?displayProperty=fullName>
75+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorSByteNonFaultingSignExtendToInt64%2A?displayProperty=fullName>
76+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorSByteNonFaultingSignExtendToUInt16%2A?displayProperty=fullName>
77+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorSByteNonFaultingSignExtendToUInt32%2A?displayProperty=fullName>
78+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorSByteNonFaultingSignExtendToUInt64%2A?displayProperty=fullName>
79+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorUInt16NonFaultingZeroExtendToInt32%2A?displayProperty=fullName>
80+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorUInt16NonFaultingZeroExtendToInt64%2A?displayProperty=fullName>
81+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorUInt16NonFaultingZeroExtendToUInt32%2A?displayProperty=fullName>
82+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorUInt16NonFaultingZeroExtendToUInt64%2A?displayProperty=fullName>
83+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorUInt32NonFaultingZeroExtendToInt64%2A?displayProperty=fullName>
84+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorUInt32NonFaultingZeroExtendToUInt64%2A?displayProperty=fullName>

‎docs/core/compatibility/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@ items:
2828
href: core-libraries/10.0/obsolete-apis.md
2929
- name: ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change
3030
href: core-libraries/10.0/activity-sampling.md
31+
- name: Arm64 SVE NonFaulting loads require mask parameter
32+
href: core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md
3133
- name: C# 14 overload resolution with span parameters
3234
href: core-libraries/10.0/csharp-overload-resolution.md
3335
- name: Consistent shift behavior in generic math

0 commit comments

Comments
 (0)