From 66c4bbb283d394ba74ef9f71f2b56cd75fbf1f5e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 8 Aug 2025 22:44:06 +0000 Subject: [PATCH 1/4] Initial plan From 9cf1d26394cf95e2c69a85ceb8b5201678491bb0 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 8 Aug 2025 22:53:36 +0000 Subject: [PATCH 2/4] Add breaking change documentation for Arm64 SVE NonFaulting loads mask parameter Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- docs/core/compatibility/10.0.md | 1 + .../sve-nonfaulting-loads-mask-parameter.md | 84 +++++++++++++++++++ docs/core/compatibility/toc.yml | 2 + 3 files changed, 87 insertions(+) create mode 100644 docs/core/compatibility/core-libraries/10.0/sve-nonfaulting-loads-mask-parameter.md 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 From b8b334d07580894ede08748d998a9a5770f0c560 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 11 Aug 2025 15:03:18 -0700 Subject: [PATCH 3/4] human edits --- docs/core/compatibility/10.0.md | 2 +- .../sve-nonfaulting-loads-mask-parameter.md | 89 +++++++++---------- docs/core/compatibility/toc.yml | 2 +- 3 files changed, 44 insertions(+), 49 deletions(-) diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index fe1de4d239186..a5596254a0d88 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -35,7 +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 | +| [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 index d4e8873ae1999..86bb696b3e75c 100644 --- 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 @@ -1,46 +1,41 @@ --- -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 +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 +# 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. +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 +.NET 10 Preview 7 ## Previous behavior -NonFaulting load APIs took only an address parameter and would load a full vector: +Previously, nonfaulting load APIs took only an address parameter and loaded a full vector: ```csharp -// .NET 9 behavior Vector result = Sve.LoadVectorByteNonFaultingZeroExtendToInt16(address); +``` + +To do nonfaulting load with masked-out elements, you had to use : -// To do masked loading, you had to use ConditionalSelect -Vector maskedResult = Sve.ConditionalSelect(mask, - Sve.LoadVectorByteNonFaultingZeroExtendToInt16(address), +```csharp +Vector maskedResult = Sve.ConditionalSelect( + mask, + Sve.LoadVectorByteNonFaultingZeroExtendToInt16(address), zero); ``` ## New behavior -NonFaulting load APIs now require a mask parameter as the first argument: +Starting in .NET 10, 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); -``` +To do a nonfaulting load for all elements, use code similar to the following: `Sve.LoadVector*NonFaulting*(Sve.CreateTrueMask*(), addr);` ## Type of breaking change @@ -48,37 +43,37 @@ This change can affect [binary compatibility](../../categories.md#binary-compati ## 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. +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)`. -- 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)`. +- 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 d9edea268ea75..d4f8bee596345 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -28,7 +28,7 @@ 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 + - 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 From 0c91af5439b4e1a127556835e07e3de3783969c5 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 11 Aug 2025 15:14:42 -0700 Subject: [PATCH 4/4] tweaks --- .../10.0/sve-nonfaulting-loads-mask-parameter.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 index 86bb696b3e75c..b67428c0e94e9 100644 --- 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 @@ -8,7 +8,7 @@ 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. +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 @@ -33,9 +33,9 @@ Vector maskedResult = Sve.ConditionalSelect( ## New behavior -Starting in .NET 10, nonfaulting load APIs now require a mask parameter as the first argument. +Starting in .NET 10, nonfaulting load APIs require a mask parameter as the first argument. -To do a nonfaulting load for all elements, use code similar to the following: `Sve.LoadVector*NonFaulting*(Sve.CreateTrueMask*(), addr);` +To do a nonfaulting load for all elements, create and pass a true mask: `Sve.LoadVector*NonFaulting*(Sve.CreateTrueMask*(), addr);` ## Type of breaking change @@ -52,6 +52,7 @@ This change was necessary because a nonfaulting load updates the first fault reg ## Affected APIs +- - - - @@ -64,7 +65,6 @@ This change was necessary because a nonfaulting load updates the first fault reg - - - -- - - -