Update Preview/Experimental Attributes in Intrinsics

docs/project/list-of-diagnostics.md

@@ -282,15 +282,21 @@ The diagnostic id values reserved for .NET Libraries analyzer warnings are `SYSL
 APIs can be marked as `[Experimental]` if their shape or functionality is included in a release but not yet officially supported. Experimental APIs offer the opportunity to collect customer feedback on these APIs in a major release, usually refining the APIs and removing the `[Experimental]` attribute in the next release. The `[Experimental]` attribute differs from `[RequiresPreviewFeatures]`, wherein:
 
 * `[RequiresPreviewFeatures]` APIs require a corresponding preview feature in another product area such as the compiler or SDK
-* `[Experimental]` APIs are entirely self-contained within the libraries and do not require preview features in other parts of the product
+    - Using these APIs requires enabling preview features for the the project and all its consumers
+* `[Experimental]` APIs are self-contained within the libraries and do not require preview features in other parts of the product
+    - These APIs can be used by suppressing specific diagnostics without enabling preview features for the project
 
-The diagnostic id values reserved for experimental APIs are `SYSLIB5001` through `SYSLIB5999`. When marking an API as `[Experimental]`, claim the next three-digit identifier in the `SYSLIB5###` sequence and add it to the list below. The URL template for all experimental APIs is `https://aka.ms/dotnet-warnings/{0}`. The `{0}` placeholder is replaced by the compiler with the `SYSLIB5###` identifier.
+See [Preview APIs - .NET | Microsoft Learn](https://learn.microsoft.com/dotnet/fundamentals/apicompat/preview-apis) for more information.
 
 ### Experimental Diagnostics (`SYSLIB5001` - `SYSLIB5999`)
 
+The diagnostic id values reserved for experimental APIs are `SYSLIB5001` through `SYSLIB5999`. When marking an API as `[Experimental]`, claim the next three-digit identifier in the `SYSLIB5###` sequence and add it to the list below. The URL template for all experimental APIs is `https://aka.ms/dotnet-warnings/{0}`. The `{0}` placeholder is replaced by the compiler with the `SYSLIB5###` identifier.
+
 Diagnostic id values for experimental APIs must not be recycled, as that could silently opt customers into new experimental APIs where they had previously suppressed the ID for a previous usage of the value.
 
 | Diagnostic ID     | Introduced | Removed | Description |
 | :---------------- | ---------: | ------: | :---------- |
 |  __`SYSLIB5001`__ |     .NET 9 |     TBD | `Tensor<T>` and related APIs in System.Numerics.Tensors are experimental in .NET 9 |
 |  __`SYSLIB5002`__ |     .NET 9 |     TBD | `SystemColors` alternate colors are experimental in .NET 9 |
+|  __`SYSLIB5003`__ |     .NET 9 |     TBD | `System.Runtime.Intrinsics.Arm.Sve` is experimental in .NET 9 |
+|  __`SYSLIB5004`__ |     .NET 9 |     TBD | `X86Base.DivRem` is experimental in .NET 9 since performance is not as optimized as `T.DivRem` |

src/coreclr/System.Private.CoreLib/System.Private.CoreLib.csproj

@@ -237,6 +237,9 @@
     <Compile Include="$(CommonPath)System\Collections\Generic\ArrayBuilder.cs">
       <Link>Common\System\Collections\Generic\ArrayBuilder.cs</Link>
     </Compile>
+    <Compile Include="$(CommonPath)System\Experimentals.cs">
+      <Link>Common\System\Experimentals.cs</Link>
+    </Compile>
     <Compile Include="src\System\RuntimeType.BoxCache.cs" />
     <Compile Include="src\System\RuntimeType.CreateUninitializedCache.CoreCLR.cs" />
     <Compile Include="src\System\RuntimeType.GenericCache.cs" />

src/coreclr/nativeaot/System.Private.CoreLib/src/System.Private.CoreLib.csproj

@@ -96,6 +96,9 @@
     <Compile Include="$(AotCommonPath)\Internal\Runtime\TypeLoader\ExternalReferencesTable.cs">
       <Link>Common\src\Internal\Runtime\TypeLoader\ExternalReferencesTable.cs</Link>
     </Compile>
+    <Compile Include="$(CommonPath)System\Experimentals.cs">
+      <Link>Common\Experimentals.cs</Link>
+    </Compile>
     <Compile Include="Internal\Runtime\FrozenObjectHeapManager.cs" />
     <Compile Include="Internal\Runtime\ThreadStatics.cs" />
     <Compile Include="Internal\Runtime\CompilerHelpers\StartupCode\StartupCodeHelpers.Extensions.cs" />

src/libraries/Common/src/System/Experimentals.cs

@@ -16,12 +16,18 @@ internal static class Experimentals
         // but retained in the table in docs\project\list-of-diagnostics.md to prevent reuse. Be sure to remove
         // suppressions from the codebase as well.
 
-        // Tensor<T> and related APIs are marked as [Experimental] in .NET 9
+        // Tensor<T> and related APIs in System.Numerics.Tensors are experimental in .NET 9
         internal const string TensorTDiagId = "SYSLIB5001";
 
         // SystemColors alternate colors are marked as [Experimental] in .NET 9
         internal const string SystemColorsDiagId = "SYSLIB5002";
 
+        // System.Runtime.Intrinsics.Arm.Sve is experimental in .NET 9
+        internal const string ArmSveDiagId = "SYSLIB5003";
+
+        // X86Base.DivRem is experimental in .NET 9 since performance is not as optimized as T.DivRem
+        internal const string X86BaseDivRemDiagId = "SYSLIB5004";
+
         // When adding a new diagnostic ID, add it to the table in docs\project\list-of-diagnostics.md as well.
         // Keep new const identifiers above this comment.
     }

src/libraries/System.Numerics.Tensors/src/System.Numerics.Tensors.csproj

@@ -7,7 +7,7 @@
     <PackageDescription>Provides support for operating over tensors.</PackageDescription>
     <GenAPIExcludeApiList>ReferenceAssemblyExclusions.txt</GenAPIExcludeApiList>
     <ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
-    <!-- SYSLIB5001: Tensor<T> and related APIs are Experimental in .NET 9 -->
+    <!-- SYSLIB5001: Tensor<T> and related APIs in System.Numerics.Tensors are experimental in .NET 9 -->
     <NoWarn>$(NoWarn);SYSLIB5001</NoWarn>
   </PropertyGroup>
 

src/libraries/System.Numerics.Tensors/tests/Net8Tests/System.Numerics.Tensors.Net8.Tests.csproj

@@ -11,6 +11,7 @@
     <TargetFramework>$(NetCoreAppCurrent)</TargetFramework>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <DefineConstants>$(DefineConstants);SNT_NET8_TESTS</DefineConstants>
+    <!-- SYSLIB5001: Tensor<T> and related APIs in System.Numerics.Tensors are experimental in .NET 9 -->
     <NoWarn>$(NoWarn);SYSLIB5001</NoWarn>
   </PropertyGroup>
 

src/libraries/System.Numerics.Tensors/tests/System.Numerics.Tensors.Tests.csproj

@@ -3,7 +3,7 @@
   <PropertyGroup>
     <TargetFrameworks>$(NetCoreAppCurrent);$(NetFrameworkMinimum)</TargetFrameworks>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
-    <!-- SYSLIB5001: Tensor<T> and related APIs are Experimental in .NET 9 -->
+    <!-- SYSLIB5001: Tensor<T> and related APIs in System.Numerics.Tensors are experimental in .NET 9 -->
     <NoWarn>$(NoWarn);SYSLIB5001</NoWarn>
   </PropertyGroup>
 

src/libraries/System.Numerics.Vectors/tests/GenericVectorTests.cs

@@ -7,7 +7,6 @@
 using System.Reflection;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
-using System.Runtime.Versioning;
 using System.Tests;
 using Xunit;
 using Xunit.Sdk;
@@ -17,7 +16,6 @@ namespace System.Numerics.Tests
     /// <summary>
     ///  Vector{T} tests that use random number generation and a unified generic test structure
     /// </summary>
-    [RequiresPreviewFeatures]
     public unsafe class GenericVectorTests
     {
         /// <summary>Verifies that two <see cref="Vector{Single}" /> values are equal, within the <paramref name="variance" />.</summary>

src/libraries/System.Private.CoreLib/src/System/Runtime/Intrinsics/Arm/Sve.PlatformNotSupported.cs

@@ -12,7 +12,7 @@ namespace System.Runtime.Intrinsics.Arm
     /// This class provides access to the ARM SVE hardware instructions via intrinsics
     /// </summary>
     [CLSCompliant(false)]
-    [System.Runtime.Versioning.RequiresPreviewFeaturesAttribute("Sve is in preview. Debugger scenario is not supported.")]
+    [Experimental(Experimentals.ArmSveDiagId, UrlFormat = Experimentals.SharedUrlFormat)]
 #if SYSTEM_PRIVATE_CORELIB
     public
 #else

src/libraries/System.Private.CoreLib/src/System/Runtime/Intrinsics/Arm/Sve.cs

@@ -13,7 +13,7 @@ namespace System.Runtime.Intrinsics.Arm
     /// </summary>
     [Intrinsic]
     [CLSCompliant(false)]
-    [System.Runtime.Versioning.RequiresPreviewFeaturesAttribute("Sve is in preview. Debugger scenario is not supported.")]
+    [Experimental(Experimentals.ArmSveDiagId, UrlFormat = Experimentals.SharedUrlFormat)]
     public abstract class Sve : AdvSimd
     {
         internal Sve() { }

src/libraries/System.Private.CoreLib/src/System/Runtime/Intrinsics/X86/AvxVnni.PlatformNotSupported.cs

@@ -2,12 +2,10 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System.Runtime.CompilerServices;
-using System.Runtime.Versioning;
 
 namespace System.Runtime.Intrinsics.X86
 {
     [CLSCompliant(false)]
-    [RequiresPreviewFeatures("AvxVnni is in preview.")]
     public abstract class AvxVnni : Avx2
     {
         internal AvxVnni() { }

src/libraries/System.Private.CoreLib/src/System/Runtime/Intrinsics/X86/AvxVnni.cs

@@ -2,13 +2,11 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System.Runtime.CompilerServices;
-using System.Runtime.Versioning;
 
 namespace System.Runtime.Intrinsics.X86
 {
     [Intrinsic]
     [CLSCompliant(false)]
-    [RequiresPreviewFeatures("AvxVnni is in preview.")]
     public abstract class AvxVnni : Avx2
     {
         internal AvxVnni() { }

src/libraries/System.Private.CoreLib/src/System/Runtime/Intrinsics/X86/X86Base.PlatformNotSupported.cs

@@ -1,6 +1,7 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 using System.Runtime.Versioning;
 
@@ -48,14 +49,14 @@ internal X64() { }
             /// unsigned __int64 _udiv128(unsigned __int64 highdividend, unsigned __int64 lowdividend, unsigned __int64 divisor, unsigned __int64* remainder)
             ///   DIV reg/m64
             /// </summary>
-            [RequiresPreviewFeatures("DivRem is in preview.")]
+            [Experimental(Experimentals.X86BaseDivRemDiagId, UrlFormat = Experimentals.SharedUrlFormat)]
             public static (ulong Quotient, ulong Remainder) DivRem(ulong lower, ulong upper, ulong divisor) { throw new PlatformNotSupportedException(); }
 
             /// <summary>
             /// __int64 _div128(__int64 highdividend, __int64 lowdividend, __int64 divisor, __int64* remainder)
             ///   DIV reg/m64
             /// </summary>
-            [RequiresPreviewFeatures("DivRem is in preview.")]
+            [Experimental(Experimentals.X86BaseDivRemDiagId, UrlFormat = Experimentals.SharedUrlFormat)]
             public static (long Quotient, long Remainder) DivRem(ulong lower, long upper, long divisor) { throw new PlatformNotSupportedException(); }
         }
 
@@ -90,25 +91,25 @@ internal X64() { }
         /// <summary>
         ///   DIV reg/m32
         /// </summary>
-        [RequiresPreviewFeatures("DivRem is in preview.")]
+        [Experimental(Experimentals.X86BaseDivRemDiagId, UrlFormat = Experimentals.SharedUrlFormat)]
         public static (uint Quotient, uint Remainder) DivRem(uint lower, uint upper, uint divisor) { throw new PlatformNotSupportedException(); }
 
         /// <summary>
         ///   IDIV reg/m32
         /// </summary>
-        [RequiresPreviewFeatures("DivRem is in preview.")]
+        [Experimental(Experimentals.X86BaseDivRemDiagId, UrlFormat = Experimentals.SharedUrlFormat)]
         public static (int Quotient, int Remainder) DivRem(uint lower, int upper, int divisor) { throw new PlatformNotSupportedException(); }
 
         /// <summary>
         ///   IDIV reg/m
         /// </summary>
-        [RequiresPreviewFeatures("DivRem is in preview.")]
+        [Experimental(Experimentals.X86BaseDivRemDiagId, UrlFormat = Experimentals.SharedUrlFormat)]
         public static (nuint Quotient, nuint Remainder) DivRem(nuint lower, nuint upper, nuint divisor) { throw new PlatformNotSupportedException(); }
 
         /// <summary>
         ///   IDIV reg/m
         /// </summary>
-        [RequiresPreviewFeatures("DivRem is in preview.")]
+        [Experimental(Experimentals.X86BaseDivRemDiagId, UrlFormat = Experimentals.SharedUrlFormat)]
         public static (nint Quotient, nint Remainder) DivRem(nuint lower, nint upper, nint divisor) { throw new PlatformNotSupportedException(); }
 
         /// <summary>

src/libraries/System.Private.CoreLib/src/System/Runtime/Intrinsics/X86/X86Base.cs

@@ -1,6 +1,7 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 using System.Runtime.Versioning;
@@ -51,14 +52,14 @@ internal X64() { }
             /// unsigned __int64 _udiv128(unsigned __int64 highdividend, unsigned __int64 lowdividend, unsigned __int64 divisor, unsigned __int64* remainder)
             ///   DIV reg/m64
             /// </summary>
-            [RequiresPreviewFeatures("DivRem is in preview.")]
+            [Experimental(Experimentals.X86BaseDivRemDiagId, UrlFormat = Experimentals.SharedUrlFormat)]
             public static (ulong Quotient, ulong Remainder) DivRem(ulong lower, ulong upper, ulong divisor) => DivRem(lower, upper, divisor);
 
             /// <summary>
             /// __int64 _div128(__int64 highdividend, __int64 lowdividend, __int64 divisor, __int64* remainder)
             ///   DIV reg/m64
             /// </summary>
-            [RequiresPreviewFeatures("DivRem is in preview.")]
+            [Experimental(Experimentals.X86BaseDivRemDiagId, UrlFormat = Experimentals.SharedUrlFormat)]
             public static (long Quotient, long Remainder) DivRem(ulong lower, long upper, long divisor) => DivRem(lower, upper, divisor);
         }
 
@@ -99,26 +100,26 @@ public static unsafe (int Eax, int Ebx, int Ecx, int Edx) CpuId(int functionId,
         /// unsigned _udiv64(unsigned __int64 dividend, unsigned divisor, unsigned* remainder)
         ///   DIV reg/m32
         /// </summary>
-        [RequiresPreviewFeatures("DivRem is in preview.")]
+        [Experimental(Experimentals.X86BaseDivRemDiagId, UrlFormat = Experimentals.SharedUrlFormat)]
         public static (uint Quotient, uint Remainder) DivRem(uint lower, uint upper, uint divisor) => DivRem(lower, upper, divisor);
 
         /// <summary>
         /// int _div64(__int64 dividend, int divisor, int* remainder)
         ///   IDIV reg/m32
         /// </summary>
-        [RequiresPreviewFeatures("DivRem is in preview.")]
+        [Experimental(Experimentals.X86BaseDivRemDiagId, UrlFormat = Experimentals.SharedUrlFormat)]
         public static (int Quotient, int Remainder) DivRem(uint lower, int upper, int divisor) => DivRem(lower, upper, divisor);
 
         /// <summary>
         ///   IDIV reg/m
         /// </summary>
-        [RequiresPreviewFeatures("DivRem is in preview.")]
+        [Experimental(Experimentals.X86BaseDivRemDiagId, UrlFormat = Experimentals.SharedUrlFormat)]
         public static (nuint Quotient, nuint Remainder) DivRem(nuint lower, nuint upper, nuint divisor) => DivRem(lower, upper, divisor);
 
         /// <summary>
         ///   IDIV reg/m
         /// </summary>
-        [RequiresPreviewFeatures("DivRem is in preview.")]
+        [Experimental(Experimentals.X86BaseDivRemDiagId, UrlFormat = Experimentals.SharedUrlFormat)]
         public static (nint Quotient, nint Remainder) DivRem(nuint lower, nint upper, nint divisor) => DivRem(lower, upper, divisor);
 
         /// <summary>

src/libraries/System.Runtime.Intrinsics/ref/System.Runtime.Intrinsics.cs

@@ -4312,7 +4312,7 @@ internal Arm64() { }
         }
     }
     [System.CLSCompliantAttribute(false)]
-    [System.Runtime.Versioning.RequiresPreviewFeaturesAttribute("Sve is in preview. Debugger scenario is not supported.")]
+    [System.Diagnostics.CodeAnalysis.ExperimentalAttribute("SYSLIB5003", UrlFormat = "https://aka.ms/dotnet-warnings/{0}")]
     public abstract partial class Sve : System.Runtime.Intrinsics.Arm.AdvSimd
     {
         internal Sve() { }
@@ -8107,7 +8107,6 @@ internal X64() { }
         }
     }
     [System.CLSCompliantAttribute(false)]
-    [System.Runtime.Versioning.RequiresPreviewFeaturesAttribute("AvxVnni is in preview.")]
     public abstract class AvxVnni : System.Runtime.Intrinsics.X86.Avx2
     {
         internal AvxVnni() { }
@@ -8957,22 +8956,22 @@ public abstract partial class X86Base
         internal X86Base() { }
         public static bool IsSupported { get { throw null; } }
         public static (int Eax, int Ebx, int Ecx, int Edx) CpuId(int functionId, int subFunctionId) { throw null; }
-        [System.Runtime.Versioning.RequiresPreviewFeaturesAttribute("DivRem is in preview.")]
+        [System.Diagnostics.CodeAnalysis.ExperimentalAttribute("SYSLIB5004", UrlFormat = "https://aka.ms/dotnet-warnings/{0}")]
         public static (uint Quotient, uint Remainder) DivRem(uint lower, uint upper, uint divisor) { throw null; }
-        [System.Runtime.Versioning.RequiresPreviewFeaturesAttribute("DivRem is in preview.")]
+        [System.Diagnostics.CodeAnalysis.ExperimentalAttribute("SYSLIB5004", UrlFormat = "https://aka.ms/dotnet-warnings/{0}")]
         public static (int Quotient, int Remainder) DivRem(uint lower, int upper, int divisor) { throw null; }
-        [System.Runtime.Versioning.RequiresPreviewFeaturesAttribute("DivRem is in preview.")]
+        [System.Diagnostics.CodeAnalysis.ExperimentalAttribute("SYSLIB5004", UrlFormat = "https://aka.ms/dotnet-warnings/{0}")]
         public static (nuint Quotient, nuint Remainder) DivRem(nuint lower, nuint upper, nuint divisor) { throw null; }
-        [System.Runtime.Versioning.RequiresPreviewFeaturesAttribute("DivRem is in preview.")]
+        [System.Diagnostics.CodeAnalysis.ExperimentalAttribute("SYSLIB5004", UrlFormat = "https://aka.ms/dotnet-warnings/{0}")]
         public static (nint Quotient, nint Remainder) DivRem(nuint lower, nint upper, nint divisor) { throw null; }
         public static void Pause() { throw null; }
         public abstract partial class X64
         {
             internal X64() { }
             public static bool IsSupported { get { throw null; } }
-            [System.Runtime.Versioning.RequiresPreviewFeaturesAttribute("DivRem is in preview.")]
+            [System.Diagnostics.CodeAnalysis.ExperimentalAttribute("SYSLIB5004", UrlFormat = "https://aka.ms/dotnet-warnings/{0}")]
             public static (ulong Quotient, ulong Remainder) DivRem(ulong lower, ulong upper, ulong divisor) { throw null; }
-            [System.Runtime.Versioning.RequiresPreviewFeaturesAttribute("DivRem is in preview.")]
+            [System.Diagnostics.CodeAnalysis.ExperimentalAttribute("SYSLIB5004", UrlFormat = "https://aka.ms/dotnet-warnings/{0}")]
             public static (long Quotient, long Remainder) DivRem(ulong lower, long upper, long divisor) { throw null; }
         }
     }

src/libraries/System.Runtime.Intrinsics/src/System.Runtime.Intrinsics.csproj

@@ -6,6 +6,10 @@
     <UseCompilerGeneratedDocXmlFile>false</UseCompilerGeneratedDocXmlFile>
   </PropertyGroup>
 
+  <ItemGroup>
+    <Compile Include="$(CommonPath)System\Experimentals.cs" Link="Common\System\Experimentals.cs" />
+  </ItemGroup>
+
   <ItemGroup>
     <ProjectReference Include="$(CoreLibProject)" />
   </ItemGroup>