Skip to content

Commit d6b51cf

Browse files
CopilotCopilot
authored
Document breaking change: Arm64 SVE NonFaulting loads require mask parameter (dotnet#47907)
1 parent ba47c6c commit d6b51cf

File tree

3 files changed

+82
-0
lines changed

3 files changed

+82
-0
lines changed

‎docs/core/compatibility/10.0.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
3939
| Title | Type of change | Introduced version |
4040
|-------|-------------------|--------------------|
4141
| [ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change](core-libraries/10.0/activity-sampling.md) | Behavioral change | Preview 1 |
42+
| [Arm64 SVE nonfaulting loads require mask](core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md) | Binary/source incompatible | Preview 1 |
4243
| [C# 14 overload resolution with span parameters](core-libraries/10.0/csharp-overload-resolution.md) | Behavioral change | Preview 1 |
4344
| [Consistent shift behavior in generic math](core-libraries/10.0/generic-math.md) | Behavioral change | Preview 1 |
4445
| [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: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
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: 08/11/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` parameter in the first position. This change affects all methods with `LoadVector*NonFaulting` in their name in the <xref:System.Runtime.Intrinsics.Arm.Sve?displayProperty=nameWithType> class.
12+
13+
## Version introduced
14+
15+
.NET 10 Preview 7
16+
17+
## Previous behavior
18+
19+
Previously, nonfaulting load APIs took only an address parameter and loaded a full vector:
20+
21+
```csharp
22+
Vector<short> result = Sve.LoadVectorByteNonFaultingZeroExtendToInt16(address);
23+
```
24+
25+
To do nonfaulting load with masked-out elements, you had to use <xref:System.Runtime.Intrinsics.Arm.Sve.ConditionalSelect*>:
26+
27+
```csharp
28+
Vector<short> maskedResult = Sve.ConditionalSelect(
29+
mask,
30+
Sve.LoadVectorByteNonFaultingZeroExtendToInt16(address),
31+
zero);
32+
```
33+
34+
## New behavior
35+
36+
Starting in .NET 10, nonfaulting load APIs require a mask parameter as the first argument.
37+
38+
To do a nonfaulting load for all elements, create and pass a true mask: `Sve.LoadVector*NonFaulting*(Sve.CreateTrueMask*(), addr);`
39+
40+
## Type of breaking change
41+
42+
This change can affect [binary compatibility](../../categories.md#binary-compatibility) and [source compatibility](../../categories.md#source-compatibility).
43+
44+
## Reason for change
45+
46+
This change was necessary because a nonfaulting load updates the first fault register (FFR) depending on which vector lanes are loaded. The standard conversion of `ConditionalSelect(mask, LoadVectorNonFaulting(addr), zero)` to a masked load can't be used because it doesn't properly handle the FFR register state. Therefore, the only valid way to implement a masked nonfaulting load is by exposing it as a dedicated API.
47+
48+
## Recommended action
49+
50+
- For existing uses of `Sve.ConditionalSelect(mask, Sve.LoadVector*NonFaulting*(addr), zero)`, replace them with `Sve.LoadVector*NonFaulting*(mask, addr)`.
51+
- Update other uses of nonfaulting loads to include a true mask: `Sve.LoadVector*NonFaulting*(Sve.CreateTrueMask*(), addr)`.
52+
53+
## Affected APIs
54+
55+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorNonFaulting%2A?displayProperty=fullName>
56+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorByteNonFaultingZeroExtendToInt16(System.Byte*)?displayProperty=fullName>
57+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorByteNonFaultingZeroExtendToInt32(System.Byte*)?displayProperty=fullName>
58+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorByteNonFaultingZeroExtendToInt64(System.Byte*)?displayProperty=fullName>
59+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorByteNonFaultingZeroExtendToUInt16(System.Byte*)?displayProperty=fullName>
60+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorByteNonFaultingZeroExtendToUInt32(System.Byte*)?displayProperty=fullName>
61+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorByteNonFaultingZeroExtendToUInt64(System.Byte*)?displayProperty=fullName>
62+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorInt16NonFaultingSignExtendToInt32(System.Int16*)?displayProperty=fullName>
63+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorInt16NonFaultingSignExtendToInt64(System.Int16*)?displayProperty=fullName>
64+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorInt16NonFaultingSignExtendToUInt32(System.Int16*)?displayProperty=fullName>
65+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorInt16NonFaultingSignExtendToUInt64(System.Int16*)?displayProperty=fullName>
66+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorInt32NonFaultingSignExtendToInt64(System.Int32*)?displayProperty=fullName>
67+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorInt32NonFaultingSignExtendToUInt64(System.Int32*)?displayProperty=fullName>
68+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorSByteNonFaultingSignExtendToInt16(System.SByte*)?displayProperty=fullName>
69+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorSByteNonFaultingSignExtendToInt32(System.SByte*)?displayProperty=fullName>
70+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorSByteNonFaultingSignExtendToInt64(System.SByte*)?displayProperty=fullName>
71+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorSByteNonFaultingSignExtendToUInt16(System.SByte*)?displayProperty=fullName>
72+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorSByteNonFaultingSignExtendToUInt32(System.SByte*)?displayProperty=fullName>
73+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorSByteNonFaultingSignExtendToUInt64(System.SByte*)?displayProperty=fullName>
74+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorUInt16NonFaultingZeroExtendToInt32(System.UInt16*)?displayProperty=fullName>
75+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorUInt16NonFaultingZeroExtendToInt64(System.UInt16*)?displayProperty=fullName>
76+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorUInt16NonFaultingZeroExtendToUInt32(System.UInt16*)?displayProperty=fullName>
77+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorUInt16NonFaultingZeroExtendToUInt64(System.UInt16*)?displayProperty=fullName>
78+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorUInt32NonFaultingZeroExtendToInt64(System.UInt32*)?displayProperty=fullName>
79+
- <xref:System.Runtime.Intrinsics.Arm.Sve.LoadVectorUInt32NonFaultingZeroExtendToUInt64(System.UInt32*)?displayProperty=fullName>

‎docs/core/compatibility/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@ items:
3636
href: core-libraries/10.0/obsolete-apis.md
3737
- name: ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change
3838
href: core-libraries/10.0/activity-sampling.md
39+
- name: Arm64 SVE nonfaulting loads require mask
40+
href: core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md
3941
- name: C# 14 overload resolution with span parameters
4042
href: core-libraries/10.0/csharp-overload-resolution.md
4143
- name: Consistent shift behavior in generic math

0 commit comments

Comments
 (0)