diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 545e946cadccf..fe1de4d239186 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 parameter](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..d4e8873ae1999 --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md @@ -0,0 +1,84 @@ +--- +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: 01/31/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` argument as the first position. This affects all methods with "NonFaulting" in their name in the class. + +## Version introduced + +.NET 10 + +## Previous behavior + +NonFaulting load APIs took only an address parameter and would load a full vector: + +```csharp +// .NET 9 behavior +Vector result = Sve.LoadVectorByteNonFaultingZeroExtendToInt16(address); + +// To do masked loading, you had to use ConditionalSelect +Vector maskedResult = Sve.ConditionalSelect(mask, + Sve.LoadVectorByteNonFaultingZeroExtendToInt16(address), + zero); +``` + +## New behavior + +NonFaulting load APIs now require a mask parameter as the first argument: + +```csharp +// .NET 10 behavior - mask parameter required +Vector result = Sve.LoadVectorByteNonFaultingZeroExtendToInt16( + Sve.CreateTrueMaskInt16(), address); + +// Masked loading is now done directly +Vector maskedResult = Sve.LoadVectorByteNonFaultingZeroExtendToInt16( + mask, address); +``` + +## 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 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. + +## Recommended action + +- For existing uses of `Sve.ConditionalSelect(mask, Sve.LoadVector*NonFaulting*(addr), zero)`, replace them with `Sve.LoadVector*NonFaulting*(mask, addr)`. +- 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)`. + +## Affected APIs + +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 5d759fa5537af..d9edea268ea75 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 parameter + 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