ARM64 arch and feature options

Author: michelleangela

docs/build/reference/arch-arm64.md

@@ -1,24 +1,31 @@
 ---
 description: "Learn more about: /arch (ARM64)"
 title: "/arch (ARM64)"
-ms.date: 08/30/2022
+ms.date: 05/24/2024
 ---
 # `/arch` (ARM64)
 
-Specifies the architecture for code generation on ARM64. For more information on **`/arch`** for other target architectures, see [`/arch` (x86)](arch-x86.md), [`/arch` (x64)](arch-x64.md), and [`/arch` (ARM)](arch-arm.md).
+Specifies the Arm A-Profile architecture extension for code generation on ARM64. For more information on **`/arch`** for other target architectures, see [`/arch` (x86)](arch-x86.md), [`/arch` (x64)](arch-x64.md), and [`/arch` (ARM)](arch-arm.md).
 
 ## Syntax
 
-> **`/arch:`**\[**`armv8.0`**-**`armv8.8`**]
+>**`/arch:<armv8.0|armv8.1|armv8.2|armv8.3|armv8.4|armv8.5|armv8.6|armv8.7|armv8.8|armv8.9>`**[[+feature]](feature-arm64.md)\
+>**`/arch:<armv9.0|armv9.1|armv9.2|armv9.3|armv9.4>`**[[+feature]](feature-arm64.md)
 
 ## Arguments
 
-**`/arch:armv8.0`** through **`/arch:armv8.8`**\
-Optional. Specifies minimum CPU extension requirements for ARMv8.x-A. The default is **`/arch:armv8.0`**.
+**`/arch:armv8.x`**\
+Specifies the Armv8-A architecture, where **`x`** is a required extension value from **`0`** to **`9`**<sup>1</sup>. By default, the compiler uses the **`/arch:armv8.0`** behavior if no architecture is specified.
+
+**`/arch:armv9.x`**<sup>2</sup>\
+Specifies the Armv9-A architecture, where **`x`** is a required extension value from **`0`** to **`4`**. By default, the compiler uses the **`/arch:armv8.0`** behavior if no architecture is specified.
 
 ## Remarks
 
-You may specify a CPU extension requirement from Armv8.0-A through Armv8.8-A. However, depending on your version of Visual Studio, the compiler may not yet generate instructions from all feature sets required by the extension level you specify. For example, **`/arch:armv8.1`** allows the `_Interlocked*` intrinsic functions to use the appropriate atomic instruction that was introduced with the ARMv8.1 extension, FEAT_LSE, but compiler support requires Visual Studio 2022 version 17.2 or later.
+You may specify an ARM64 extension from Armv8.0-A through Armv8.9-A and Armv9.0-A through Armv9.4-A. Optionally, one or more architecture features can be enabled by appending a feature argument to the option<sup>3</sup>. For example, in order to target Armv8.0-A and enable feature FEAT_LSE, append feature argument **`lse`** so that the option becomes **`/arch:armv8.0+lse`**. For more information about available features and their requirements, see [`/feature` (ARM64)](feature-arm64.md)<sup>3</sup>.
+
+> [!NOTE]
+> Depending on your version of Visual Studio, the compiler may not yet generate instructions from all feature sets required by the extension level you specify. For example, **`/arch:armv8.1`** allows the `*Interlocked*` intrinsic functions to use the appropriate atomic instruction that was introduced with the Armv8.1-A extension feature FEAT_LSE, but compiler support requires Visual Studio 2022 version 17.2 or later.
 
 The `_M_ARM64` macro is defined by default when compiling for an ARM64 target. For more information, see [Predefined macros](../../preprocessor/predefined-macros.md).
 
@@ -30,12 +37,16 @@ When you use [`/clr`](clr-common-language-runtime-compilation.md) to compile, **
 
 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page.
 
-1. In the **Additional options** box, add *`/arch:armv8.0`* or higher. Choose **OK** to save your changes.
+1. In the **Additional options** box, add *`/arch:armv8.0`* or replace `armv8.0` with a different ARM64 extension. Choose **OK** to save your changes.
 
 ### To set this compiler option programmatically
 
 - See <xref:Microsoft.VisualStudio.VCProjectEngine.VCCLCompilerTool.AdditionalOptions%2A>.
 
+<sup>1</sup> Armv8-A architecture extension `armv8.9` is available starting in Visual Studio 2022 version 17.10.\
+<sup>2</sup> Armv9-A architecture extensions are available starting in Visual Studio 2022 version 17.10.\
+<sup>3</sup> ARM architecture feature enablement is available starting in Visual Studio 2022 version 17.10.
+
 ## See also
 
 [`/arch` (Minimum CPU architecture)](arch-minimum-cpu-architecture.md)\

docs/build/reference/compiler-options-listed-alphabetically.md

@@ -16,7 +16,7 @@ This table contains an alphabetical list of compiler options. For a list of comp
 | [`/?`](help-compiler-command-line-help.md) | Lists the compiler options. |
 | [`/AI<dir>`](ai-specify-metadata-directories.md) | Specifies a directory to search to resolve file references passed to the [`#using`](../../preprocessor/hash-using-directive-cpp.md) directive. |
 | [`/analyze`](analyze-code-analysis.md) | Enables code analysis. |
-| [`/arch:<IA32|SSE|SSE2|AVX|AVX2|AVX512>`](arch-x86.md) | Minimum CPU architecture requirements. IA32, SSE, and SSE2 are x86 only. |
+| [`/arch`](arch-minimum-cpu-architecture.md) | Minimum CPU architecture requirements. |
 | `/arm64EC` | Generate code compatible with the arm64EC ABI. |
 | [`/await`](await-enable-coroutine-support.md) | Enable coroutines (resumable functions) extensions. |
 | [`/await:strict`](await-enable-coroutine-support.md) | Enable standard C++20 coroutine support with earlier language versions. |
@@ -65,6 +65,7 @@ This table contains an alphabetical list of compiler options. For a list of comp
 | [`/FC`](fc-full-path-of-source-code-file-in-diagnostics.md) | Displays the full path of source code files passed to *cl.exe* in diagnostic text. |
 | [`/Fd`](fd-program-database-file-name.md) | Renames program database file. |
 | [`/Fe`](fe-name-exe-file.md) | Renames the executable file. |
+| [`/feature`](feature-arm64.md) | Enable architecture features.<sup>17.10</sup> |
 | [`/FI<file>`](fi-name-forced-include-file.md) | Preprocesses the specified include file. |
 | [`/Fi`](fi-preprocess-output-file-name.md) | Specifies the preprocessed output file name. |
 | [`/Fm`](fm-name-mapfile.md) | Creates a mapfile. |
@@ -257,6 +258,8 @@ This table contains an alphabetical list of compiler options. For a list of comp
 | [`/Zs`](zs-syntax-check-only.md) | Checks syntax only. |
 | [`/ZW`](zw-windows-runtime-compilation.md) | Produces an output file to run on the Windows Runtime. |
 
+<sup>17.10</sup> This option is available starting in Visual Studio 2022 version 17.10.
+
 ## See also
 
 [MSVC compiler options](compiler-options.md)\

docs/build/reference/compiler-options-listed-by-category.md

@@ -28,7 +28,7 @@ This article contains a categorical list of compiler options. For an alphabetica
 
 | Option | Purpose |
 |--|--|
-| [`/arch:<IA32|SSE|SSE2|AVX|AVX2|AVX512>`](arch-x86.md) | Minimum CPU architecture requirements. IA32, SSE, and SSE2 are x86 only. |
+| [`/arch`](arch-minimum-cpu-architecture.md) | Minimum CPU architecture requirements. |
 | [`/clr`](clr-common-language-runtime-compilation.md) | Produces an output file to run on the common language runtime. |
 | [`/clr:implicitKeepAlive-`](clr-common-language-runtime-compilation.md) | Turn off implicit emission of `System::GC::KeepAlive(this)`. |
 | [`/clr:initialAppDomain`](clr-common-language-runtime-compilation.md) | Enable initial AppDomain behavior of Visual C++ 2002. |
@@ -42,6 +42,7 @@ This article contains a categorical list of compiler options. For an alphabetica
 | [`/EHc`](eh-exception-handling-model.md) | `extern "C"` defaults to `nothrow`. |
 | [`/EHr`](eh-exception-handling-model.md) | Always generate `noexcept` runtime termination checks. |
 | [`/EHs`](eh-exception-handling-model.md) | Enable C++ exception handling (no SEH exceptions). |
+| [`/feature`](feature-arm64.md) | Enable architecture features.<sup>17.10</sup> |
 | [`/fp:contract`](fp-specify-floating-point-behavior.md) | Consider floating-point contractions when generating code. |
 | [`/fp:except[-]`](fp-specify-floating-point-behavior.md) | Consider floating-point exceptions when generating code. |
 | [`/fp:fast`](fp-specify-floating-point-behavior.md) | "fast" floating-point model; results are less predictable. |
@@ -325,6 +326,8 @@ Experimental options may only be supported by certain versions of the compiler.
 | [`/Ze`](za-ze-disable-language-extensions.md) | Deprecated. Enables language extensions. |
 | [`/Zg`](zg-generate-function-prototypes.md) | Removed in Visual Studio 2015. Generates function prototypes. |
 
+<sup>17.10</sup> This option is available starting in Visual Studio 2022 version 17.10.
+
 ## See also
 
 [C/C++ building reference](c-cpp-building-reference.md)\

docs/build/reference/feature-arm64.md

@@ -0,0 +1,46 @@
+---
+description: "Learn more about: /feature (ARM64)"
+title: "/feature (ARM64)"
+ms.date: 05/24/2024
+---
+# `/feature` (ARM64)
+
+Optionally specify one or more Arm A-Profile architecture features to enable for an ARM64 extension specified by **`/arch`** (ARM64). For more information on **`/arch`** (ARM64), see [`/arch` (ARM64)](arch-arm64.md).
+
+## Syntax
+
+> **`/feature:<arg1>`**[**`+arg2`**]
+
+## Arguments
+Specify one or more of the following available features to enable if a targeted ARM64 extension supports it.
+
+| Feature argument | Feature identifier | Optional from | Enabled by default | Description |
+|--|--|--|--|--|
+|**`lse`**   | FEAT_LSE | Armv8.0  | Armv8.1 | Large System Extensions. |
+|**`rcpc`**  | FEAT_LRCPC | Armv8.2 | Armv8.3 | Load-Acquire RCpc instructions. |
+
+## Remarks
+
+Example usage: to enable FEAT_LSE, use feature argument **`lse`** so that the option is **`/feature:lse`**.
+
+If there are conflicting feature arguments specified by **`/feature`**, the right-most feature is enabled. Enabling a feature that is not supported by a targeted architecture may cause unexpected behavior, especially if a CPU does not implement the feature.
+
+You can use either **`/feature`** or only **`/arch`** (ARM64) to specify features. For example, if you want to enable FEAT_LSE when targeting Armv8.0-A, you can either use both **`/feature:lse`** and **`/arch:armv8.0`** or only use **`/arch:armv8.0+lse`**. **`/feature`** exists as another way to specify features without having to specify them in **`/arch`** (ARM64).
+
+### To set the `/feature` compiler option in Visual Studio
+
+1. Open the **Property Pages** dialog box for the project. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md).
+
+1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page.
+
+1. In the **Additional options** box, add *`/feature:lse`* or replace `lse` with the feature to enable. Choose **OK** to save your changes.
+
+### To set this compiler option programmatically
+
+- See <xref:Microsoft.VisualStudio.VCProjectEngine.VCCLCompilerTool.AdditionalOptions%2A>.
+
+## See also
+
+[`/arch` (Minimum CPU architecture)](arch-minimum-cpu-architecture.md)\
+[MSVC compiler options](compiler-options.md)\
+[MSVC compiler command-line syntax](compiler-command-line-syntax.md)

docs/build/toc.yml

@@ -560,6 +560,8 @@ items:
                   href: ../build/reference/favor-optimize-for-architecture-specifics.md
                 - name: /FC (Full path of source code file in diagnostics)
                   href: ../build/reference/fc-full-path-of-source-code-file-in-diagnostics.md
+                - name: /feature (Enable architecture features)
+                  href: ../build/reference/feature-arm64.md
                 - name: /fp (Specify floating-point behavior)
                   href: ../build/reference/fp-specify-floating-point-behavior.md
                 - name: /fpcvt (Floating-point to unsigned integer conversion behavior)