diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 545e946cadccf..a5596254a0d88 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -35,6 +35,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | Title | Type of change | Introduced version | |-------|-------------------|--------------------| | [ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change](core-libraries/10.0/activity-sampling.md) | Behavioral change | Preview 1 | +| [Arm64 SVE nonfaulting loads require mask](core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md) | Binary/source incompatible | Preview 1 | | [C# 14 overload resolution with span parameters](core-libraries/10.0/csharp-overload-resolution.md) | Behavioral change | Preview 1 | | [Consistent shift behavior in generic math](core-libraries/10.0/generic-math.md) | Behavioral change | Preview 1 | | [Default trace context propagator updated to W3C standard](core-libraries/10.0/default-trace-context-propagator.md) | Behavioral change | Preview 4 | diff --git a/docs/core/compatibility/core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md b/docs/core/compatibility/core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md new file mode 100644 index 0000000000000..b67428c0e94e9 --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md @@ -0,0 +1,79 @@ +--- +title: "Breaking change: Arm64 SVE nonfaulting loads require mask parameter" +description: "Learn about the breaking change in .NET 10 where Arm64 SVE nonfaulting load APIs now require a mask parameter as the first argument." +ms.date: 08/11/2025 +ai-usage: ai-assisted +ms.custom: https://github.com/dotnet/docs/issues/47439 +--- + +# Arm64 SVE nonfaulting loads require mask parameter + +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 class. + +## Version introduced + +.NET 10 Preview 7 + +## Previous behavior + +Previously, nonfaulting load APIs took only an address parameter and loaded a full vector: + +```csharp +Vector result = Sve.LoadVectorByteNonFaultingZeroExtendToInt16(address); +``` + +To do nonfaulting load with masked-out elements, you had to use : + +```csharp +Vector maskedResult = Sve.ConditionalSelect( + mask, + Sve.LoadVectorByteNonFaultingZeroExtendToInt16(address), + zero); +``` + +## New behavior + +Starting in .NET 10, nonfaulting load APIs require a mask parameter as the first argument. + +To do a nonfaulting load for all elements, create and pass a true mask: `Sve.LoadVector*NonFaulting*(Sve.CreateTrueMask*(), addr);` + +## Type of breaking change + +This change can affect [binary compatibility](../../categories.md#binary-compatibility) and [source compatibility](../../categories.md#source-compatibility). + +## Reason for change + +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. + +## Recommended action + +- For existing uses of `Sve.ConditionalSelect(mask, Sve.LoadVector*NonFaulting*(addr), zero)`, replace them with `Sve.LoadVector*NonFaulting*(mask, addr)`. +- Update other uses of nonfaulting loads to include a true mask: `Sve.LoadVector*NonFaulting*(Sve.CreateTrueMask*(), addr)`. + +## Affected APIs + +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 5d759fa5537af..d4f8bee596345 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -28,6 +28,8 @@ items: href: core-libraries/10.0/obsolete-apis.md - name: ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change href: core-libraries/10.0/activity-sampling.md + - name: Arm64 SVE nonfaulting loads require mask + href: core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md - name: C# 14 overload resolution with span parameters href: core-libraries/10.0/csharp-overload-resolution.md - name: Consistent shift behavior in generic math