Merge branch 'main' of https://github.com/MicrosoftDocs/cpp-docs-pr into build-insights

Author: TylerMSFT

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

@@ -197,7 +197,7 @@ This table contains an alphabetical list of compiler options. For a list of comp
 | [`/vmv`](vmm-vms-vmv-general-purpose-representation.md) | Declares virtual inheritance. |
 | [`/volatile:iso`](volatile-volatile-keyword-interpretation.md) | Acquire/release semantics not guaranteed on volatile accesses. |
 | [`/volatile:ms`](volatile-volatile-keyword-interpretation.md) | Acquire/release semantics guaranteed on volatile accesses. |
-| `/volatileMetadata` | Generate metadata on volatile memory accesses. |
+| [`/volatileMetadata`](volatile.md) | Generate metadata on volatile memory accesses. |
 | [`/w`](compiler-option-warning-level.md) | Disable all warnings. |
 | [`/W0`, `/W1`, `/W2`, `/W3`, `/W4`](compiler-option-warning-level.md) | Set output warning level. |
 | [`/w1<n>`, `/w2<n>`, `/w3<n>`, `/w4<n>`](compiler-option-warning-level.md) | Set warning level for the specified warning. |

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

@@ -262,7 +262,7 @@ This article contains a categorical list of compiler options. For an alphabetica
 | [`/utf-8`](utf-8-set-source-and-executable-character-sets-to-utf-8.md) | Set source and execution character sets to UTF-8. |
 | [`/V`](v-version-number.md) | Deprecated. Sets the version string. |
 | [`/validate-charset`](validate-charset-validate-for-compatible-characters.md) | Validate UTF-8 files for only compatible characters. |
-| `/volatileMetadata` | Generate metadata on volatile memory accesses. |
+| [`/volatileMetadata`](volatile.md) | Generate metadata on volatile memory accesses. |
 | [`/Yc`](yc-create-precompiled-header-file.md) | Create *`.PCH`* file. |
 | [`/Yd`](yd-place-debug-information-in-object-file.md) | Deprecated. Places complete debugging information in all object files. Use [`/Zi`](z7-zi-zi-debug-information-format.md) instead. |
 | [`/Yl`](yl-inject-pch-reference-for-debug-library.md) | Injects a PCH reference when creating a debug library. |

docs/build/reference/headerunit.md

@@ -1,7 +1,7 @@
 ---
 title: "/headerUnit (Use header unit IFC)"
 description: "Use the /headerUnit compiler option to associate a header file with the header unit to import in its place."
-ms.date: 02/01/2022
+ms.date: 5/28/2024
 f1_keywords: ["/headerUnit"]
 helpviewer_keywords: ["/headerUnit", "Use header unit IFC"]
 author: "tylermsft"
@@ -14,8 +14,8 @@ Imports a header unit. Tells the compiler where to find the *`.ifc`* file (the b
 ## Syntax
 
 > **`/headerUnit`** *`header-filename`*=*`ifc-filename`*\
-> **`/headerUnit:quote`** \[*`header-filename`*=*`ifc-filename`*\]\
-> **`/headerUnit:angle`** \[*`header-filename`*=*`ifc-filename`*\]
+> **`/headerUnit:quote`** *`header-filename`*=*`ifc-filename`*\
+> **`/headerUnit:angle`** *`header-filename`*=*`ifc-filename`*
 
 ### Arguments
 
@@ -39,7 +39,7 @@ When the compiler comes across `import "file";` or `import <file>;` this compile
 
 - **`/headerUnit:angle`** looks up the compiled header unit file using the same rules as `#include <file>`.
 
-The compiler can't map a single *`header-name`* to multiple *`.ifc`* files. Mapping multiple *`header-name`* arguments to a single *`.ifc`* is possible, but it isn't recommended. The contents of the *`.ifc`* are imported as if it was only the header specified by *`header-name`*.
+The compiler can't map a single *`header-name`* to multiple *`.ifc`* files. You can map multiple *`header-name`* arguments to a single *`.ifc`*. The contents of the *`.ifc`* are imported as if it was only the header specified by *`header-name`*.
 
 The compiler implicitly enables the new preprocessor when this option is used. If any form of `/headerUnit` is specified on the command line, then [`/Zc:preprocessor`](zc-preprocessor.md) is added to the command line by the compiler. To opt out of the implicit `/Zc:preprocessor`, specify: `/Zc:preprocessor-`
 

docs/build/reference/volatile.md

@@ -0,0 +1,42 @@
+---
+description: "Learn more about: /volatileMetadata"
+title: "/volatileMetadata (Generate metadata on volatile memory accesses)"
+ms.date: 5/29/2024
+f1_keywords: ["/volatileMetadata"]
+helpviewer_keywords: ["/volatileMetadata", "-volatileMetadata compiler option", "/volatileMetadata compiler option", "volatileMetadata"]
+---
+# `/volatileMetadata` (Generate metadata on volatile memory accesses)
+
+Generate metadata for volatile memory accesses to improve performance when running x64 code on ARM64.
+
+## Syntax
+
+```cpp
+/volatileMetadata[-]
+```
+
+## Arguments
+
+**`-`**\
+Turns off `/volatileMetadata`. This may result in worse performance when your code runs in emulation mode on ARM64 because the emulator pessimistically assumes that every load/store needs a barrier.
+
+## Remarks
+
+Starting with Visual Studio 2019 16.10, `/volatileMetadata` is on by default when generating x64 code. It improves the emulation performance of x64 code on ARM64 by generating metadata that identifies volatile memory addresses. An emulator can use this metadata to improve performance by not using acquire/release semantics on those accesses it knows aren't volatile. Without this metadata, the emulator assumes that all addresses are volatile and uses acquire and release semantics.
+
+One side effect of `/volatileMetadata` is you may see `npad` macros used in the generated code. This macro expands to a specified number of `NOP` instructions that create an address to associate with a memory barrier. That address is then recorded in the metadata to indicate that acquire/release semantics should be used to access it.
+
+`/volatileMetadata` is ignored when targeting x86.
+
+`/volatileMetadata` can be disabled by using `/volatileMetadata-`.
+
+`/volatileMetadata` is ignored when targeting x86.
+
+## Requirements
+
+Visual Studio 2019 version 16.10 or later.
+
+## See also
+
+[MSVC Compiler Options](compiler-options.md)\
+[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)

docs/build/toc.yml

@@ -746,6 +746,8 @@ items:
                   href: ../build/reference/vmm-vms-vmv-general-purpose-representation.md
                 - name: /volatile (volatile keyword interpretation)
                   href: ../build/reference/volatile-volatile-keyword-interpretation.md
+                - name: /volatileMetadata
+                  href: ../build/reference/volatile.md
                 - name: /w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, /WX (Warning level)
                   href: ../build/reference/compiler-option-warning-level.md
                 - name: /WL (Enable one-line diagnostics)