draft /voltilemetadata

Author: TylerMSFT

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

@@ -196,7 +196,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

@@ -261,7 +261,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/volatile.md

@@ -0,0 +1,40 @@
+---
+description: "Learn more about: /volatilemetadata"
+title: "/volatilemetadata (Generate metadata on volatile memory accesses)"
+ms.date: 5/28/2024
+f1_keywords: ["/volatilemetadata"]
+helpviewer_keywords: ["/volatilemetadata", "-volatilemetadata compiler option", "/volatilemetadata compiler option", "volatilemetadata"]
+---
+# `/volatilemetadata` (Generate metadata on volatile memory accesses)
+
+Generate metadata on volatile memory accesses to improve performance when running x64 code on ARM.
+
+## Syntax
+
+```cpp
+/volatilemetdata[-]
+```
+
+## Arguments
+
+**`-`**\
+Turns off `/volatileMetadata`. This may result in worse performance if your code is run in emulation mode on ARM because the emulator will pessimistically assume that every load/store needs a barrier.
+
+## Remarks
+
+Starting with Visual Studio 2019 16.10, `/volatileMetadata` is on by default when generating x64 code meant to run on ARM. It improves the emulation performance of x64 code on ARM by generating metadata that identifies volatile memory addresses. This metadata can be used by an emulator to improve performance because it then knows which addresses aren't volatile. Without this metadata, the emulator assumes that all addresses are volatile, and uses acquire and release semantics to access them.
+
+One side effect `/volatileMetadata` is you may see `npad` macros in the generated code. This macro expands to a specified number of NOP instructions to create an address to associate with the memory barrier. That address is then recorded in the metadata.
+
+`/volatileMetadata` can be disabled by using `/volatileMetadata-`.
+
+`/volatileMetadata` is ignored when targeting x86.
+
+## Requirements
+
+Visual Studio 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

@@ -744,6 +744,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)