From 836ad0f1402821e2b5088d5b0a25374ccec6dc21 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 9 Jan 2026 18:32:50 +0000 Subject: [PATCH 1/4] Initial plan From ad1ae9b587f18729c5d7b85a6dfdc48c6d4a836d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 9 Jan 2026 18:37:24 +0000 Subject: [PATCH 2/4] Add breaking change documentation for minimum hardware requirements in .NET 11 Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- docs/core/compatibility/11.md | 6 + .../jit/11/minimum-hardware-requirements.md | 109 ++++++++++++++++++ docs/core/compatibility/toc.yml | 4 + 3 files changed, 119 insertions(+) create mode 100644 docs/core/compatibility/jit/11/minimum-hardware-requirements.md diff --git a/docs/core/compatibility/11.md b/docs/core/compatibility/11.md index 38e7062d947b6..7e345c85522dc 100644 --- a/docs/core/compatibility/11.md +++ b/docs/core/compatibility/11.md @@ -26,3 +26,9 @@ If you're migrating an app to .NET 11, the breaking changes listed here might af | Title | Type of change | |-------|-------------------| | [Japanese Calendar minimum supported date corrected](globalization/11/japanese-calendar-min-date.md) | Behavioral change | + +## JIT compiler + +| Title | Type of change | +|-------------------------------------------------------------------|-------------------| +| [Minimum hardware requirements updated](jit/11/minimum-hardware-requirements.md) | Behavioral change | diff --git a/docs/core/compatibility/jit/11/minimum-hardware-requirements.md b/docs/core/compatibility/jit/11/minimum-hardware-requirements.md new file mode 100644 index 0000000000000..72b4b684fe4dc --- /dev/null +++ b/docs/core/compatibility/jit/11/minimum-hardware-requirements.md @@ -0,0 +1,109 @@ +--- +title: "Breaking change: Minimum hardware requirements updated" +description: "Learn about the breaking change in .NET 11 where minimum hardware requirements have been updated for x86/x64 and Arm64 architectures." +ms.date: 01/09/2026 +ai-usage: ai-assisted +ms.custom: https://github.com/dotnet/docs/issues/50793 +--- + +# Minimum hardware requirements updated + +The minimum hardware requirements for .NET 11 have been updated to require more modern instruction sets on both x86/x64 and Arm64 architectures. Additionally, the ReadyToRun (R2R) compilation targets have been updated to take advantage of newer hardware capabilities. + +## Version introduced + +.NET 11 Preview 1 + +## Previous behavior + +By default, .NET would successfully launch and run on older hardware. The baseline instruction sets were: + +### Arm64 + +- **Apple**: Apple M1 (approximately armv8.5-a with AdvSimd, CRC, DOTPROD, LSE, RCPC, RCPC2, and RDMA) +- **Linux**: armv8.0-a (basic AdvSimd support) +- **Windows**: armv8.0-a + +### x86/x64 + +- **All platforms**: x86-64-v1 (CMOV, CX8, SSE, SSE2) + +Individual applications could opt in to higher baselines or explicitly use [hardware intrinsics](xref:System.Runtime.Intrinsics) that raised the baseline for their scenario. + +## New behavior + +.NET will fail to run on older hardware that doesn't meet the new minimum requirements and may print a message similar to the following: + +> The current CPU is missing one or more of the baseline instruction sets. + +A more descriptive message may be provided in some scenarios that lists the concrete hardware requirements for a given operating system and architecture. + +The updated minimum requirements are: + +### Arm64 + +| Operating System | JIT/AOT Minimum | R2R Target | +| ---------------- | --------------- | --------------- | +| Apple | Apple M1 | Apple M1 | +| Linux | armv8.0-a | armv8.0-a + LSE | +| Windows | armv8.0-a + LSE | armv8.2-a + RCPC | + +### x86/x64 + +| Operating System | JIT/AOT Minimum | R2R Target | +| ---------------- | --------------- | ------------- | +| Apple | x86-64-v2 | x86-64-v2 | +| Linux | x86-64-v2 | x86-64-v3 | +| Windows | x86-64-v2 | x86-64-v3 | + +The **x86-64-v2** baseline adds support for CX16, POPCNT, SSE3, SSSE3, SSE4.1, and SSE4.2 instruction sets. + +The **x86-64-v3** baseline adds support for AVX, AVX2, BMI1, BMI2, F16C, FMA, LZCNT, and MOVBE instruction sets. + +For ReadyToRun capable assemblies, there may be additional startup overhead on some hardware that is supported but doesn't meet the expected support for a typical device. + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +.NET supports a broad range of hardware, often beyond the minimum hardware requirements put in place by the underlying operating system. However, this support adds significant complexity to the codebase, particularly for older hardware that is unlikely to still be in use. Additionally, it defines a "lowest common denominator" that AOT targets must default to, which can lead to reduced performance in some scenarios. + +The update to the minimum baseline was made to: + +- Reduce the maintenance complexity of the codebase +- Better align with the documented (and often enforced) hardware requirements of the underlying operating system +- Improve performance by allowing the runtime to assume support for modern instruction sets + +### Arm64 details + +- **Apple**: No change. The Apple M1 chips are approximately equivalent to armv8.5-a and provide support for at least the AdvSimd (NEON), CRC, DOTPROD, LSE, RCPC, RCPC2, and RDMA instruction sets. + +- **Linux**: No change to the minimum hardware. Devices such as Raspberry Pi that may only provide support for the AdvSimd instruction set continue to be supported. The ReadyToRun target has been updated to include the LSE instruction set, which may result in additional jitting overhead if you launch an application on older hardware. + +- **Windows**: The baseline is updated to require the LSE instruction set. This is required by [Windows 11](https://learn.microsoft.com/windows-hardware/design/minimum/minimum-hardware-requirements-overview) and by all Arm64 CPUs officially supported by [Windows 10](https://learn.microsoft.com/windows-hardware/design/minimum/windows-processor-requirements). It's also inline with the Arm SBSA (Server Base System Architecture) requirements. The ReadyToRun target has been updated to be armv8.2-a + RCPC (this provides support for at least AdvSimd, CRC, LSE, RCPC, and RDMA), which covers the majority of hardware officially supported. + +### x86/x64 details + +For all three operating systems, the baseline is updated from x86-64-v1 to x86-64-v2. This changes the hardware from only guaranteeing CMOV, CX8, SSE, and SSE2 to also guaranteeing CX16, POPCNT, SSE3, SSSE3, SSE4.1, and SSE4.2. This is required by Windows 11 and by all x86/x64 CPUs officially supported on Windows 10. It includes all chips still officially supported by Intel and AMD, with the last older chips having gone out of support around 2013. + +The ReadyToRun target has been updated to x86-64-v3 for Windows and Linux, which additionally includes the AVX, AVX2, BMI1, BMI2, F16C, FMA, LZCNT, and MOVBE instruction sets. The ReadyToRun target remains unchanged for Apple at x86-64-v2. + +## Recommended action + +Developers on no longer supported hardware should consider updating. Such hardware is officially out of support and may not boot on operating system versions that are supported by .NET. + +If you're running .NET on hardware that doesn't meet these requirements: + +- Upgrade to newer hardware that meets the minimum requirements +- If upgrading isn't possible, consider using an earlier version of .NET that supports your hardware + +## Affected APIs + +This affects all of .NET. All applications running on .NET 11 must meet the new minimum hardware requirements. + +## See also + +- [Hardware intrinsics](xref:System.Runtime.Intrinsics) +- [ReadyToRun deployment](/dotnet/core/deploying/ready-to-run) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 1286012e0f7ba..6e3dda344859a 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -18,6 +18,10 @@ items: items: - name: Japanese Calendar minimum supported date corrected href: globalization/11/japanese-calendar-min-date.md + - name: JIT compiler + items: + - name: Minimum hardware requirements updated + href: jit/11/minimum-hardware-requirements.md - name: .NET 10 items: - name: Overview From 96cffe0b467fd586f6c32f21a40f40182797932d Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 9 Jan 2026 15:09:40 -0800 Subject: [PATCH 3/4] human edits --- .../jit/11/minimum-hardware-requirements.md | 93 ++++++------------- 1 file changed, 30 insertions(+), 63 deletions(-) diff --git a/docs/core/compatibility/jit/11/minimum-hardware-requirements.md b/docs/core/compatibility/jit/11/minimum-hardware-requirements.md index 72b4b684fe4dc..d8578a05305f9 100644 --- a/docs/core/compatibility/jit/11/minimum-hardware-requirements.md +++ b/docs/core/compatibility/jit/11/minimum-hardware-requirements.md @@ -3,64 +3,54 @@ title: "Breaking change: Minimum hardware requirements updated" description: "Learn about the breaking change in .NET 11 where minimum hardware requirements have been updated for x86/x64 and Arm64 architectures." ms.date: 01/09/2026 ai-usage: ai-assisted -ms.custom: https://github.com/dotnet/docs/issues/50793 +ms.custom: https://github.com/dotnet/docs/issues/51003 --- # Minimum hardware requirements updated The minimum hardware requirements for .NET 11 have been updated to require more modern instruction sets on both x86/x64 and Arm64 architectures. Additionally, the ReadyToRun (R2R) compilation targets have been updated to take advantage of newer hardware capabilities. -## Version introduced - -.NET 11 Preview 1 - -## Previous behavior - -By default, .NET would successfully launch and run on older hardware. The baseline instruction sets were: - ### Arm64 -- **Apple**: Apple M1 (approximately armv8.5-a with AdvSimd, CRC, DOTPROD, LSE, RCPC, RCPC2, and RDMA) -- **Linux**: armv8.0-a (basic AdvSimd support) -- **Windows**: armv8.0-a +For Apple, there's no change to the minimum hardware or the `ReadyToRun` target. The `Apple M1` chips are approximately equivalent to `armv8.5-a` and so provide support for at least the `AdvSimd` (NEON), `CRC`, `DOTPROD`, `LSE`, `RCPC`, `RCPC2`, and `RDMA` instruction sets. -### x86/x64 +For Linux, there's no change to the minimum hardware. .NET continues to support devices such as Raspberry PI that might only provide support for the `AdvSimd` instruction set. The `ReadyToRun` target has been updated to include the `LSE` instruction set, which might result in additional jitting overhead if you launch an application. -- **All platforms**: x86-64-v1 (CMOV, CX8, SSE, SSE2) +For Windows, the baseline is updated to require the `LSE` instruction set. This is [required by Windows 11](/windows-hardware/design/minimum/minimum-hardware-requirements-overview) and by [all Arm64 CPUs officially supported by Windows 10](/windows-hardware/design/minimum/windows-processor-requirements). Additionally, it's inline with the `Arm SBSA` (Server Base System Architecture) requirements. The `ReadyToRun` target has been updated to be `armv8.2-a + RCPC` (this provides support for at least `AdvSimd`, `CRC`, `LSE`, `RCPC`, and `RDMA`), which covers the majority of hardware officially supported. -Individual applications could opt in to higher baselines or explicitly use [hardware intrinsics](xref:System.Runtime.Intrinsics) that raised the baseline for their scenario. +| OS | Previous JIT/AOT minimum | New JIT/AOT minimum | Previous R2R target | New R2R target | +|---------|--------------------------|---------------------|---------------------|------------------| +| Apple | Apple M1 | (No change) | Apple M1 | (No change) | +| Linux | armv8.0-a | (No change) | armv8.0-a | armv8.0a + LSE | +| Windows | armv8.0-a | armv8.0-a + LSE | armv8.0-a | armv8.2-a + RCPC | -## New behavior +### x86/x64 -.NET will fail to run on older hardware that doesn't meet the new minimum requirements and may print a message similar to the following: +For all three operating systems (Apple, Linux, and Windows), the baseline is updated from `x86-64-v1` to `x86-64-v2`. This changes the hardware from only guaranteeing `CMOV`, `CX8`, `SSE`, and `SSE2` to also guaranteeing `CX16`, `POPCNT`, `SSE3`, `SSSE3`, `SSE4.1`, and `SSE4.2`. This guarantee is required by Windows 11 and by all x86/x64 CPUs officially supported on Windows 10. It includes all chips still officially supported by Intel/AMD, with the last older chips having gone out of support around 2013. -> The current CPU is missing one or more of the baseline instruction sets. +The `ReadyToRun` target has been updated to `x86-64-v3` for Windows and Linux, while it remains unchanged for Apple, which additionally includes the `AVX`, `AVX2`, `BMI1`, `BMI2`, `F16C`, `FMA`, `LZCNT`, and `MOVBE` instruction sets. -A more descriptive message may be provided in some scenarios that lists the concrete hardware requirements for a given operating system and architecture. +| OS | Previous JIT/AOT minimum | New JIT/AOT minimum | Previous R2R target | New R2R target | +|---------|--------------------------|---------------------|---------------------|----------------| +| Apple | x86-64-v1 | x86-64-v2 | x86-64-v2 | (No change) | +| Linux | x86-64-v1 | x86-64-v2 | x86-64-v2 | x86-64-v3 | +| Windows | x86-64-v1 | x86-64-v2 | x86-64-v2 | x86-64-v3 | -The updated minimum requirements are: +## Version introduced -### Arm64 +.NET 11 Preview 1 -| Operating System | JIT/AOT Minimum | R2R Target | -| ---------------- | --------------- | --------------- | -| Apple | Apple M1 | Apple M1 | -| Linux | armv8.0-a | armv8.0-a + LSE | -| Windows | armv8.0-a + LSE | armv8.2-a + RCPC | +## Previous behavior -### x86/x64 +By default, .NET successfully launched and ran on older hardware. Individual applications might have opted-in to higher baselines or explicitly used [hardware intrinsics](xref:System.Runtime.Intrinsics) that raised the baseline for their scenario. -| Operating System | JIT/AOT Minimum | R2R Target | -| ---------------- | --------------- | ------------- | -| Apple | x86-64-v2 | x86-64-v2 | -| Linux | x86-64-v2 | x86-64-v3 | -| Windows | x86-64-v2 | x86-64-v3 | +## New behavior -The **x86-64-v2** baseline adds support for CX16, POPCNT, SSE3, SSSE3, SSE4.1, and SSE4.2 instruction sets. +Starting with .NET 11, .NET fails to run on older hardware and might print a message similar to the following. (In some scenarios, a more descriptive message might be provided that lists the concrete hardware requirements for a given operating system and architecture.) -The **x86-64-v3** baseline adds support for AVX, AVX2, BMI1, BMI2, F16C, FMA, LZCNT, and MOVBE instruction sets. +> The current CPU is missing one or more of the baseline instruction sets. -For ReadyToRun capable assemblies, there may be additional startup overhead on some hardware that is supported but doesn't meet the expected support for a typical device. +For [`ReadyToRun`](../../../deploying/ready-to-run.md)-capable assemblies, there might be additional startup overhead on some supported hardware that doesn't meet the expected support for a typical device. ## Type of breaking change @@ -68,42 +58,19 @@ This change is a [behavioral change](../../categories.md#behavioral-change). ## Reason for change -.NET supports a broad range of hardware, often beyond the minimum hardware requirements put in place by the underlying operating system. However, this support adds significant complexity to the codebase, particularly for older hardware that is unlikely to still be in use. Additionally, it defines a "lowest common denominator" that AOT targets must default to, which can lead to reduced performance in some scenarios. - -The update to the minimum baseline was made to: - -- Reduce the maintenance complexity of the codebase -- Better align with the documented (and often enforced) hardware requirements of the underlying operating system -- Improve performance by allowing the runtime to assume support for modern instruction sets - -### Arm64 details +.NET supports a broad range of hardware, often above and beyond the minimum hardware requirements put in place by the underlying operating system (OS). .NET also has built-in support for taking advantage of the hardware it's actively running on for JIT scenarios. However, this support adds significant complexity to the codebase, particularly for much older hardware that's unlikely to still be in use. Additionally, it defines a "lowest common denominator" that AOT targets must default to which can, in some domain-specific scenarios, lead to reduced performance for applications. -- **Apple**: No change. The Apple M1 chips are approximately equivalent to armv8.5-a and provide support for at least the AdvSimd (NEON), CRC, DOTPROD, LSE, RCPC, RCPC2, and RDMA instruction sets. - -- **Linux**: No change to the minimum hardware. Devices such as Raspberry Pi that may only provide support for the AdvSimd instruction set continue to be supported. The ReadyToRun target has been updated to include the LSE instruction set, which may result in additional jitting overhead if you launch an application on older hardware. - -- **Windows**: The baseline is updated to require the LSE instruction set. This is required by [Windows 11](https://learn.microsoft.com/windows-hardware/design/minimum/minimum-hardware-requirements-overview) and by all Arm64 CPUs officially supported by [Windows 10](https://learn.microsoft.com/windows-hardware/design/minimum/windows-processor-requirements). It's also inline with the Arm SBSA (Server Base System Architecture) requirements. The ReadyToRun target has been updated to be armv8.2-a + RCPC (this provides support for at least AdvSimd, CRC, LSE, RCPC, and RDMA), which covers the majority of hardware officially supported. - -### x86/x64 details - -For all three operating systems, the baseline is updated from x86-64-v1 to x86-64-v2. This changes the hardware from only guaranteeing CMOV, CX8, SSE, and SSE2 to also guaranteeing CX16, POPCNT, SSE3, SSSE3, SSE4.1, and SSE4.2. This is required by Windows 11 and by all x86/x64 CPUs officially supported on Windows 10. It includes all chips still officially supported by Intel and AMD, with the last older chips having gone out of support around 2013. - -The ReadyToRun target has been updated to x86-64-v3 for Windows and Linux, which additionally includes the AVX, AVX2, BMI1, BMI2, F16C, FMA, LZCNT, and MOVBE instruction sets. The ReadyToRun target remains unchanged for Apple at x86-64-v2. +The update to the minimum baseline was made to reduce the maintenance complexity of the codebase and to better align with the documented (and often enforced) hardware requirements of the underlying OS. ## Recommended action -Developers on no longer supported hardware should consider updating. Such hardware is officially out of support and may not boot on operating system versions that are supported by .NET. - -If you're running .NET on hardware that doesn't meet these requirements: - -- Upgrade to newer hardware that meets the minimum requirements -- If upgrading isn't possible, consider using an earlier version of .NET that supports your hardware +If you're using hardware that's no longer supported, consider updating. Such hardware is officially out of support and might not boot on operating system versions that are supported by .NET. ## Affected APIs -This affects all of .NET. All applications running on .NET 11 must meet the new minimum hardware requirements. +This change affects all of .NET. ## See also - [Hardware intrinsics](xref:System.Runtime.Intrinsics) -- [ReadyToRun deployment](/dotnet/core/deploying/ready-to-run) +- [ReadyToRun deployment](../../../deploying/ready-to-run.md) From d606b7cc99d37ccf8e51ba5fc43a592a3b8b8290 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 9 Jan 2026 15:20:36 -0800 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../compatibility/jit/11/minimum-hardware-requirements.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/core/compatibility/jit/11/minimum-hardware-requirements.md b/docs/core/compatibility/jit/11/minimum-hardware-requirements.md index d8578a05305f9..a487f6f557102 100644 --- a/docs/core/compatibility/jit/11/minimum-hardware-requirements.md +++ b/docs/core/compatibility/jit/11/minimum-hardware-requirements.md @@ -3,7 +3,7 @@ title: "Breaking change: Minimum hardware requirements updated" description: "Learn about the breaking change in .NET 11 where minimum hardware requirements have been updated for x86/x64 and Arm64 architectures." ms.date: 01/09/2026 ai-usage: ai-assisted -ms.custom: https://github.com/dotnet/docs/issues/51003 +ms.custom: https://github.com/dotnet/docs/issues/48045 --- # Minimum hardware requirements updated @@ -14,14 +14,14 @@ The minimum hardware requirements for .NET 11 have been updated to require more For Apple, there's no change to the minimum hardware or the `ReadyToRun` target. The `Apple M1` chips are approximately equivalent to `armv8.5-a` and so provide support for at least the `AdvSimd` (NEON), `CRC`, `DOTPROD`, `LSE`, `RCPC`, `RCPC2`, and `RDMA` instruction sets. -For Linux, there's no change to the minimum hardware. .NET continues to support devices such as Raspberry PI that might only provide support for the `AdvSimd` instruction set. The `ReadyToRun` target has been updated to include the `LSE` instruction set, which might result in additional jitting overhead if you launch an application. +For Linux, there's no change to the minimum hardware. .NET continues to support devices such as Raspberry Pi that might only provide support for the `AdvSimd` instruction set. The `ReadyToRun` target has been updated to include the `LSE` instruction set, which might result in additional jitting overhead if you launch an application. For Windows, the baseline is updated to require the `LSE` instruction set. This is [required by Windows 11](/windows-hardware/design/minimum/minimum-hardware-requirements-overview) and by [all Arm64 CPUs officially supported by Windows 10](/windows-hardware/design/minimum/windows-processor-requirements). Additionally, it's inline with the `Arm SBSA` (Server Base System Architecture) requirements. The `ReadyToRun` target has been updated to be `armv8.2-a + RCPC` (this provides support for at least `AdvSimd`, `CRC`, `LSE`, `RCPC`, and `RDMA`), which covers the majority of hardware officially supported. | OS | Previous JIT/AOT minimum | New JIT/AOT minimum | Previous R2R target | New R2R target | |---------|--------------------------|---------------------|---------------------|------------------| | Apple | Apple M1 | (No change) | Apple M1 | (No change) | -| Linux | armv8.0-a | (No change) | armv8.0-a | armv8.0a + LSE | +| Linux | armv8.0-a | (No change) | armv8.0-a | armv8.0-a + LSE | | Windows | armv8.0-a | armv8.0-a + LSE | armv8.0-a | armv8.2-a + RCPC | ### x86/x64