From 03c38e22390fc630da0103184306ed13896d62af Mon Sep 17 00:00:00 2001 From: Michelle Matias <38734287+michelleangela@users.noreply.github.com> Date: Wed, 15 May 2024 13:54:09 -0700 Subject: [PATCH 1/6] ARM64 feature option --- docs/build/reference/arch-arm64.md | 20 +++++--- .../compiler-options-listed-alphabetically.md | 1 + .../compiler-options-listed-by-category.md | 1 + docs/build/reference/feature-arm64.md | 46 +++++++++++++++++++ docs/build/toc.yml | 2 + 5 files changed, 63 insertions(+), 7 deletions(-) create mode 100644 docs/build/reference/feature-arm64.md diff --git a/docs/build/reference/arch-arm64.md b/docs/build/reference/arch-arm64.md index 873f808dadc..6d8ec1f1b95 100644 --- a/docs/build/reference/arch-arm64.md +++ b/docs/build/reference/arch-arm64.md @@ -1,24 +1,30 @@ --- description: "Learn more about: /arch (ARM64)" title: "/arch (ARM64)" -ms.date: 08/30/2022 +ms.date: 05/16/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:`**[[+feature]](feature-arm64.md)\ +>**`/arch:`**[[+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 +36,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 diff --git a/docs/build/reference/compiler-options-listed-alphabetically.md b/docs/build/reference/compiler-options-listed-alphabetically.md index 8e9f1572eda..a3ac39da0f6 100644 --- a/docs/build/reference/compiler-options-listed-alphabetically.md +++ b/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`](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. | diff --git a/docs/build/reference/compiler-options-listed-by-category.md b/docs/build/reference/compiler-options-listed-by-category.md index 141f35bcfda..e3a3395a4bc 100644 --- a/docs/build/reference/compiler-options-listed-by-category.md +++ b/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. | diff --git a/docs/build/reference/feature-arm64.md b/docs/build/reference/feature-arm64.md new file mode 100644 index 00000000000..826e00a7935 --- /dev/null +++ b/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:`**[**`+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. + +The use of **`/feature`** in combination of **`/arch`** (ARM64) results in the same behavior as appending feature arguments to **`/arch`** (ARM64). For example, specifying both **`/feature:lse`** and **`/arch:armv8.0`** is the same as only specifying **`/arch:armv8.0+lse`**. **`/feature`** exists to provide the flexibility of specifying a feature and architecture through different compiler options. + +### 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 . + +## 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) diff --git a/docs/build/toc.yml b/docs/build/toc.yml index 5c58c095572..e86f96782be 100644 --- a/docs/build/toc.yml +++ b/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) From eda64bc0ad7692e5723c8826faf00d2f15b0dbe3 Mon Sep 17 00:00:00 2001 From: Michelle Matias <38734287+michelleangela@users.noreply.github.com> Date: Wed, 15 May 2024 13:58:40 -0700 Subject: [PATCH 2/6] fix date --- docs/build/reference/arch-arm64.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build/reference/arch-arm64.md b/docs/build/reference/arch-arm64.md index 6d8ec1f1b95..1f95bb173dd 100644 --- a/docs/build/reference/arch-arm64.md +++ b/docs/build/reference/arch-arm64.md @@ -1,7 +1,7 @@ --- description: "Learn more about: /arch (ARM64)" title: "/arch (ARM64)" -ms.date: 05/16/2024 +ms.date: 05/15/2024 --- # `/arch` (ARM64) From 08a8ec3f9eee5a1e6589f2a726a97ba7b66df09e Mon Sep 17 00:00:00 2001 From: Michelle Matias <38734287+michelleangela@users.noreply.github.com> Date: Wed, 15 May 2024 14:17:43 -0700 Subject: [PATCH 3/6] fix note format --- docs/build/reference/arch-arm64.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/build/reference/arch-arm64.md b/docs/build/reference/arch-arm64.md index 1f95bb173dd..d694a6e5b9a 100644 --- a/docs/build/reference/arch-arm64.md +++ b/docs/build/reference/arch-arm64.md @@ -24,7 +24,8 @@ Specifies the Armv9-A architecture, where **`x`** is a required extension value 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. +> [!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). From 53b271d28cdbe295dcb3f74557b91377aacca2d0 Mon Sep 17 00:00:00 2001 From: Michelle Matias <38734287+michelleangela@users.noreply.github.com> Date: Wed, 15 May 2024 14:56:59 -0700 Subject: [PATCH 4/6] change wording --- docs/build/reference/feature-arm64.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build/reference/feature-arm64.md b/docs/build/reference/feature-arm64.md index 826e00a7935..187a23b402c 100644 --- a/docs/build/reference/feature-arm64.md +++ b/docs/build/reference/feature-arm64.md @@ -25,7 +25,7 @@ Example usage: to enable FEAT_LSE, use feature argument **`lse`** so that the op 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. -The use of **`/feature`** in combination of **`/arch`** (ARM64) results in the same behavior as appending feature arguments to **`/arch`** (ARM64). For example, specifying both **`/feature:lse`** and **`/arch:armv8.0`** is the same as only specifying **`/arch:armv8.0+lse`**. **`/feature`** exists to provide the flexibility of specifying a feature and architecture through different compiler options. +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 From 313e8254624511973e1c7f35428770519334fda9 Mon Sep 17 00:00:00 2001 From: Michelle Matias <38734287+michelleangela@users.noreply.github.com> Date: Wed, 15 May 2024 15:40:20 -0700 Subject: [PATCH 5/6] re-word --- docs/build/reference/arch-arm64.md | 2 +- docs/build/reference/feature-arm64.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build/reference/arch-arm64.md b/docs/build/reference/arch-arm64.md index d694a6e5b9a..5bbc8eb0078 100644 --- a/docs/build/reference/arch-arm64.md +++ b/docs/build/reference/arch-arm64.md @@ -25,7 +25,7 @@ Specifies the Armv9-A architecture, where **`x`** is a required extension value 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. +> 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). diff --git a/docs/build/reference/feature-arm64.md b/docs/build/reference/feature-arm64.md index 187a23b402c..948ac7078bb 100644 --- a/docs/build/reference/feature-arm64.md +++ b/docs/build/reference/feature-arm64.md @@ -25,7 +25,7 @@ Example usage: to enable FEAT_LSE, use feature argument **`lse`** so that the op 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). +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 From acd3fdf8b2f3412a5a31e9cd686423775117de76 Mon Sep 17 00:00:00 2001 From: Michelle Matias <38734287+michelleangela@users.noreply.github.com> Date: Wed, 15 May 2024 15:50:10 -0700 Subject: [PATCH 6/6] Update /arch link --- docs/build/reference/compiler-options-listed-alphabetically.md | 2 +- docs/build/reference/compiler-options-listed-by-category.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build/reference/compiler-options-listed-alphabetically.md b/docs/build/reference/compiler-options-listed-alphabetically.md index a3ac39da0f6..a2596f2d3dc 100644 --- a/docs/build/reference/compiler-options-listed-alphabetically.md +++ b/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`](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:`](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. | diff --git a/docs/build/reference/compiler-options-listed-by-category.md b/docs/build/reference/compiler-options-listed-by-category.md index e3a3395a4bc..2fa925bdadb 100644 --- a/docs/build/reference/compiler-options-listed-by-category.md +++ b/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:`](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. |