Add Arm64 forceInterlockedFunctions option (#5822)

emilybao · TylerMSFT · web-flow · commit ed103093aafb · 2025-04-14T11:13:51.000-07:00
* Learn Editor: Update compiler-options-listed-by-category.md

* Learn Editor: Update compiler-options-listed-alphabetically.md

* Learn Editor: Update force-interlocked-functions.md

* Learn Editor: Update force-interlocked-functions.md

* update Metadata

* Update force-interlocked-functions.md with github id author name

* Reorder compiler options in toc.yml to be alphabetical

* Learn Editor: Update compiler-options-listed-alphabetically.md

* Learn Editor: Update compiler-options-listed-by-category.md

* Learn Editor: Update force-interlocked-functions.md

* change article metadata

* Learn Editor: Update force-interlocked-functions.md

* Fix casing in toc.yml for forceInterlockedFunctions

* Add 'items' section to toc.yml to revert previous change

* Fix indentation in toc.yml file

* Update metadata and improve documentation wording

* Update metadata in force-interlocked-functions.md

tidied up metdata

* Fix typos and improve clarity in documentation

* Update description for `/forceInterlockedFunctions` option

* Clarify CPU capability/ runtime description in documentation

* Update remark on Armv8.0 instructions

* Remove unneeded template comments and update livelock remarks in documentation

* Add "---" to metadata

---------

Co-authored-by: Tyler Whitney &lt;TylerMSFT@users.noreply.github.com&gt;
diff --git a/docs/build/reference/compiler-options-listed-alphabetically.md b/docs/build/reference/compiler-options-listed-alphabetically.md
@@ -67,6 +67,7 @@ This table contains an alphabetical list of compiler options. For a list of comp
 | [`/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> |
+| [`/forceInterlockedFunctions`](force-interlocked-functions.md) | Dynamically selects between Armv8.0 load, store exclusive instructions or Armv8.1 LSE atomic instructions based on target CPU.<sup>17.14</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. |
@@ -261,6 +262,7 @@ This table contains an alphabetical list of compiler options. For a list of comp
 | [`/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.
+<sup>17.14</sup> This option is available starting in Visual Studio 2022 version 17.14.
 
 ## See also
 
diff --git a/docs/build/reference/compiler-options-listed-by-category.md b/docs/build/reference/compiler-options-listed-by-category.md
@@ -44,6 +44,7 @@ This article contains a categorical list of compiler options. For an alphabetica
 | [`/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> |
+| [`/forceInterlockedFunctions`](force-interlocked-functions.md) | Dynamically selects between Armv8.0 load, store exclusive instructions or Armv8.1 LSE atomic instructions based on target CPU.<sup>17.14</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. |
@@ -329,6 +330,7 @@ Experimental options may only be supported by certain versions of the compiler.
 | [`/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.
+<sup>17.14</sup> This option is available starting in Visual Studio 2022 version 17.14.
 
 ## See also
 
diff --git a/docs/build/reference/force-interlocked-functions.md b/docs/build/reference/force-interlocked-functions.md
@@ -0,0 +1,55 @@
+---
+title:       "/forceInterlockedFunctions"
+description: "Learn more about /forceInterlockedFunctions"
+ms.date:     03/07/2025
+---
+# `/forceInterlockedFunctions`
+
+Dynamically selects between Armv8.0 load, store exclusive instructions or Armv8.1 Large System Extension (LSE) atomic instructions based on CPU capability at runtime.
+
+## Syntax
+
+> **`/forceInterlockedFunctions`**[**`-`**]
+
+## Remarks
+When possible, this flag avoids using Armv8.0 load and store exclusive instructions, as these instructions can result in livelocks.
+This flag forces the following interlocked intrinsics to be generated as out-of-line functions:
+
+|Operation|8|16|32|64|128|Pointer|
+|-|-------|--------|--------|--------|-------|-------|
+|Add|None|None|Full|Full|None|None|
+|And|Full|Full|Full|Full|None|None|
+|CompareExchange|Full|Full|Full|Full|Full|Full|
+|Decrement|None|Full|Full|Full|None|None|
+|Exchange|Full|Full|Full|Full|None|Full|
+|ExchangeAdd|Full|Full|Full|Full|None|None|
+|Increment|None|Full|Full|Full|None|None|
+|Or|Full|Full|Full|Full|None|None|
+|Xor|Full|Full|Full|Full|None|None|
+|bittestandreset|None|None|Full|Full|None|None|
+|bittestandset|None|None|Full|Full|None|None|
+
+Key:
+
+- **Full**: supports plain, `_acq`, `_rel`, and `_nf` forms.
+
+- **None**: Not supported
+
+For more information about interlocked intrinsics, see the "Interlocked intrinsics" section in [Arm64 Intrinsics](../../intrinsics/arm64-intrinsics.md).
+
+### To set the `/forceInterlockedFunctions` 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 *`/forceInterlockedFunctions`* to enable. Choose **OK** to save your changes.
+
+### To set this compiler option programmatically
+
+- See <xref:Microsoft.VisualStudio.VCProjectEngine.VCCLCompilerTool.AdditionalOptions%2A>.
+
+## See also
+[Arm64 Intrinsics](../../intrinsics/arm64-intrinsics.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
@@ -562,6 +562,9 @@ items:
                   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: /forceInterlockedFunctions (Generate and link with out-of-line atomic
+                    functions)
+                  href: ./reference/force-interlocked-functions.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)
