New /QSpectre flag (#5115)

TylerMSFT · TylerMSFT · web-flow · commit adb9c7fb8d4e · 2023-11-30T19:20:37.000-05:00
* new topic for /Qspectr-jmp

* add links

* acrolinx

* remove IDE portion since not implemented yet

---------

Co-authored-by: TylerMSFT &lt;Tyler.Whitney@microsoft.com&gt;
diff --git a/docs/build/reference/qspectre-jmp.md b/docs/build/reference/qspectre-jmp.md
@@ -0,0 +1,38 @@
+---
+title: "/Qspectre-jmp"
+description: "Describes the Microsoft C/C++ compiler (MSVC) /Qspectre-jmp option."
+ms.date: 11/30/2023
+helpviewer_keywords: ["/Qspectre-jmp"]
+---
+# `/Qspectre-jmp`
+
+Causes the compiler to generate an `int3` instruction (software interrupt) after unconditional direct branches. This option extends the [`/Qspectre`](qspectre.md) flag and mitigates speculative execution side-channel attacks on unconditional direct branches.
+
+## Syntax
+
+> **/Qspectre-jmp**
+
+## Remarks
+
+**`/Qspectre-jmp`** causes the compiler to detect executable instructions following unconditional direct branches. An `int3` is inserted following unconditional direct branches to ensure that no instructions are speculatively executed beyond the branch. For example, the compiler mitigates `jmp addr` by adding an `int3` instruction following the `jmp` instruction as shown here:
+
+```asm
+jmp addr
+int3
+```
+
+`/Qspectre-jmp` is off by default. It's supported for all optimization levels.
+
+### Set this compiler option programmatically
+
+To set this option programmatically, see [VCCLCompilerTool.AdditionalOptions property](/dotnet/api/microsoft.visualstudio.vcprojectengine.vcclcompilertool.additionaloptions).
+
+## See also
+
+[`/Qspectre`](qspectre.md)\
+[`/Qspectre-jmp`](qspectre-jmp.md)\
+[`/Qspectre-load`](qspectre-load.md)\
+[`/Qspectre-load-cf`](qspectre-load-cf.md)\
+[/Q options (Low-Level Operations)](q-options-low-level-operations.md)\
+[MSVC compiler options](compiler-options.md)\
+[MSVC compiler command-line syntax](compiler-command-line-syntax.md)
diff --git a/docs/build/reference/qspectre-load-cf.md b/docs/build/reference/qspectre-load-cf.md
@@ -15,7 +15,7 @@ Specifies compiler generation of serializing instructions for every control-flow
 
 ## Remarks
 
-**/Qspectre-load-cf** causes the compiler to detect `JMP`, `RET`, and `CALL` control-flow instructions that load from memory, and to insert serializing instructions after the load. Where possible, these instructions are split into a load and a control flow transfer. The load is followed by an `LFENCE` to ensure the load is protected. There are cases where the compiler can't split instructions, such as the `JMP` instruction, so it uses an alternate mitigation technique. For example, the compiler mitigates `jmp [rax]` by adding instructions to load the target non-destructively before inserting an LFENCE, as shown here:
+**/Qspectre-load-cf** causes the compiler to detect `JMP`, `RET`, and `CALL` control-flow instructions that load from memory, and to insert serializing instructions after the load. Where possible, these instructions are split into a load and a control flow transfer. The load is followed by an `LFENCE` to ensure the load is protected. There are cases where the compiler can't split instructions, such as the `JMP` instruction, so it uses an alternate mitigation technique. For example, the compiler mitigates `jmp [rax]` by adding instructions to load the target nondestructively before inserting an LFENCE, as shown here:
 
 ```asm
     xor rbx, [rax]
@@ -44,6 +44,9 @@ The **/Qspectre-load-cf** option is available in Visual Studio 2019 version 16.5
 
 ## See also
 
+[`/Qspectre`](qspectre.md)\
+[`/Qspectre-jmp`](qspectre-jmp.md)\
+[`/Qspectre-load`](qspectre-load.md)\
 [/Q options (Low-level operations)](q-options-low-level-operations.md)\
 [MSVC compiler options](compiler-options.md)\
 [MSVC compiler command-line syntax](compiler-command-line-syntax.md)
diff --git a/docs/build/reference/qspectre-load.md b/docs/build/reference/qspectre-load.md
@@ -14,7 +14,7 @@ Specifies compiler generation of serializing instructions for every load instruc
 
 ## Remarks
 
-**/Qspectre-load** causes the compiler to detect loads from memory, and insert serializing instructions after them. Control flow instructions that load memory, including `RET` and `CALL`, are split into a load and a control flow transfer. The load is followed by an `LFENCE` to ensure the load is protected. There are cases where the compiler can't split control flow instructions, such as the `jmp` instruction, so it uses an alternate mitigation technique. For example, the compiler mitigates `jmp [rax]` by adding instructions to load the target non-destructively before inserting an LFENCE, as shown here:
+**/Qspectre-load** causes the compiler to detect loads from memory, and insert serializing instructions after them. Control flow instructions that load memory, including `RET` and `CALL`, are split into a load and a control flow transfer. The load is followed by an `LFENCE` to ensure the load is protected. There are cases where the compiler can't split control flow instructions, such as the `jmp` instruction, so it uses an alternate mitigation technique. For example, the compiler mitigates `jmp [rax]` by adding instructions to load the target nondestructively before inserting an LFENCE, as shown here:
 
 ```asm
     xor rbx, [rax]
@@ -43,6 +43,9 @@ The **/Qspectre-load** option is available in Visual Studio 2019 version 16.5 an
 
 ## See also
 
+[`/Qspectre`](qspectre.md)\
+[`/Qspectre-jmp`](qspectre-jmp.md)\
+[`/Qspectre-load-cf`](qspectre-load-cf.md)\
 [/Q options (Low-Level Operations)](q-options-low-level-operations.md)\
 [MSVC compiler options](compiler-options.md)\
 [MSVC compiler command-line syntax](compiler-command-line-syntax.md)
diff --git a/docs/build/reference/qspectre.md b/docs/build/reference/qspectre.md
@@ -23,7 +23,7 @@ The **`/Qspectre`** option is off by default.
 
 In its initial release, the **`/Qspectre`** option only worked on optimized code. Starting in Visual Studio 2017 version 15.7, the **`/Qspectre`** option is supported at all optimization levels.
 
-Several Microsoft C++ libraries are also available in versions with Spectre mitigation. The Spectre-mitigated libraries for Visual Studio can be downloaded in the Visual Studio Installer. They're found in the **Individual Components** tab under **Compilers, build tools, and runtimes**, and have "Libs for Spectre" in the name. Both DLL and static runtime libraries with mitigation enabled are available for a subset of the Visual C++ runtimes: VC++ start-up code, vcruntime140, msvcp140, concrt140, and vcamp140. The DLLs are supported for application-local deployment only. The contents of the Visual C++ Runtime Libraries Redistributable haven't been modified.
+Several Microsoft C++ libraries are also available in versions with Spectre mitigation. The Spectre-mitigated libraries for Visual Studio can be downloaded in the Visual Studio Installer. They're found in the **Individual Components** tab under **Compilers, build tools, and runtimes**, and have "Libs for Spectre" in the name. Both DLL and static runtime libraries with mitigation enabled are available for a subset of the Visual C++ runtimes: VC++ start-up code, vcruntime140, msvcp140, concrt140, and vcamp140. The DLLs are supported for application-local deployment only. The contents of the Visual C++ Runtime Libraries Redistributable are unmodified.
 
 You can also install Spectre-mitigated libraries for MFC and ATL. They're found in the **Individual Components** tab under **SDKs, libraries, and frameworks**.
 
@@ -72,7 +72,7 @@ The default MSBuild-based project system in the Visual Studio IDE lets you speci
 
 ::: moniker range="msvc-150"
 
-The default MSBuild-based project system in the Visual Studio IDE lets you specify a [Spectre Mitigation](./c-cpp-prop-page.md#spectre-mitigation) property for your projects. This property sets the **`/Qspectre`** compiler option and changes the library paths to link the Spectre-mitigated runtime libraries. If these libraries aren't installed when you build your code, the build system reports warning MSB8038: "Spectre mitigation is enabled but Spectre mitigated libraries are not found". If your MFC or ATL code fails to build, and the linker reports an error such as "fatal error LNK1104: cannot open file 'oldnames.lib'", these missing libraries may be the cause.
+The default MSBuild-based project system in the Visual Studio IDE lets you specify a [Spectre Mitigation](./c-cpp-prop-page.md#spectre-mitigation) property for your projects. This property sets the **`/Qspectre`** compiler option and changes the library paths to link the Spectre-mitigated runtime libraries. If these libraries aren't installed when you build your code, the build system reports warning MSB8038: "Spectre mitigation is enabled but Spectre mitigated libraries are not found." If your MFC or ATL code fails to build, and the linker reports an error such as "fatal error LNK1104: cannot open file 'oldnames.lib'", these missing libraries may be the cause.
 
 ::: moniker-end
 
@@ -134,6 +134,9 @@ For an overview of Spectre vulnerabilities addressed by the MSVC mitigations, se
 
 ## See also
 
+[`/Qspectre-jmp`](qspectre-jmp.md)\
+[`/Qspectre-load`](qspectre-load.md)\
+[`/Qspectre-load-cf`](qspectre-load-cf.md)\
 [`/Q` options (Low-level operations)](q-options-low-level-operations.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
@@ -700,6 +700,8 @@ items:
                       href: ../build/reference/qsafe-fp-loads.md
                     - name: /Qspectre
                       href: ../build/reference/qspectre.md
+                    - name: /Qspectre-jmp
+                      href: ../build/reference/qspectre-jmp.md
                     - name: /Qspectre-load
                       href: ../build/reference/qspectre-load.md
                     - name: /Qspectre-load-cf
