Add compiler option /feature and update the /arch (ARM64) option

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/15/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`**. By default, the compiler uses the **`/arch:armv8.0`** behavior if no architecture is specified.
+
+**`/arch:armv9.x`**\
+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. 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).
+
+> [!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,7 +37,7 @@ 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 a different ARM64 extension. Choose **OK** to save your changes.
 
 ### To set this compiler option programmatically
 

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

@@ -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. |
 | [`/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. |

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

@@ -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. |
 | [`/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. |

docs/build/reference/feature-arm64.md

@@ -0,0 +1,46 @@
+---
+description: "Learn more about: /feature (ARM64)"
+title: "/feature (ARM64)"
+ms.date: 05/15/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.
+
+If you use **`/feature`** in combination of **`/arch`** (ARM64), it will result in the same behavior as appending feature arguments to **`/arch`** (ARM64). For example, if you are using both **`/feature:lse`** and **`/arch:armv8.0`**, it is the same as if you're only using **`/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)