Merge pull request #2645 from dadonenf/qspectre-load

Add /Qspectre-load documentation

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

@@ -106,6 +106,8 @@ The following is a comprehensive alphabetical list of compiler options. For a ca
 |[/Qpar (Auto-Parallelizer)](qpar-auto-parallelizer.md)|Enables automatic parallelization of loops that are marked with the [#pragma loop()](../../preprocessor/loop.md) directive.|
 |[/Qsafe_fp_loads](qsafe-fp-loads.md)|Uses integer move instructions for floating-point values and disables certain floating point load optimizations.|
 |[/Qspectre](qspectre.md)|Specifies compiler generation of instructions to mitigate certain Spectre variant 1 security vulnerabilities.|
+|[/Qspectre-load](qspectre-load.md)|Specifies compiler generation of serializing instructions to mitigate Spectre security vulnerabilities based on load instructions.|
+|[/Qspectre-load-cf](qspectre-load-cf.md)|Specifies compiler generation of serializing instructions to mitigate Spectre security vulnerabilities based on control flow instructions which load memory.|
 |[/Qvec-report (Auto-Vectorizer Reporting Level)](qvec-report-auto-vectorizer-reporting-level.md)|Enables reporting levels for automatic vectorization.|
 |[/RTC](rtc-run-time-error-checks.md)|Enables run-time error checking.|
 |[/sdl](sdl-enable-additional-security-checks.md)|Enables additional security features and warnings.|

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

@@ -62,6 +62,8 @@ This article contains a categorical list of compiler options. For an alphabetica
 |[/Qpar-report](qpar-report-auto-parallelizer-reporting-level.md)|Enables reporting levels for automatic parallelization.|
 |[/Qsafe_fp_loads](qsafe-fp-loads.md)|Uses integer move instructions for floating-point values and disables certain floating point load optimizations.|
 |[/Qspectre](qspectre.md)|Enable mitigations for CVE 2017-5753, for a class of Spectre attacks.|
+|[/Qspectre-load](qspectre-load.md)|Generate serializing instructions for every load instruction.|
+|[/Qspectre-load-cf](qspectre-load-cf.md)|Generate serializing instructions for every control flow instruction which loads memory.|
 |[/Qvec-report](qvec-report-auto-vectorizer-reporting-level.md)|Enables reporting levels for automatic vectorization.|
 |[/RTC](rtc-run-time-error-checks.md)|Enables run-time error checking.|
 |[/volatile](volatile-volatile-keyword-interpretation.md)|Selects how the volatile keyword is interpreted.|

docs/build/reference/q-options-low-level-operations.md

@@ -24,6 +24,10 @@ You can use the **/Q** compiler options to perform the following low-level compi
 
 - [/Qspectre](qspectre.md): Generates instructions to mitigate certain Spectre security vulnerabilities.
 
+- [/Qspectre-load](qspectre-load.md): Generates instructions to mitigate Spectre security vulnerabilities based on loads.
+
+- [/Qspectre-load-cf](qspectre-load-cf.md): Generates instructions to mitigate Spectre security vulnerabilities based on control flow instructions which load.
+
 - [/Qvec-report (Auto-Vectorizer Reporting Level)](qvec-report-auto-vectorizer-reporting-level.md): Enables reporting levels for automatic vectorization.
 
 ## See also

docs/build/reference/qspectre-load-cf.md

@@ -0,0 +1,49 @@
+---
+title: "/Qspectre-load-cf"
+description: "Describes the Microsoft C/C++ compiler (MSVC) /Qspectre-load-cf option."
+ms.date: "01/28/2020"
+helpviewer_keywords: ["/Qspectre-load-cf"]
+no-loc: [Qspectre-load-cf]
+---
+# /Qspectre-load-cf
+
+Specifies compiler generation of serializing instructions for every control-flow instruction that contains a load. This option performs a subset of the mitigations done by the [/Qspectre-load](qspectre-load.md) option.
+
+## Syntax
+
+> **/Qspectre-load-cf**
+
+## 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:
+
+```asm
+    xor rbx, [rax]
+    xor rbx, [rax]  ; force a load of [rax]
+    lfence          ; followed by an LFENCE
+    jmp [rax]
+```
+
+Because **/Qspectre-load-cf** stops speculation of all loads in control-flow instructions, the performance impact is high. The mitigation isn't appropriate everywhere. If there are performance critical blocks of code that don't require protection, you can disable these mitigations by using `__declspec(spectre(nomitigation))`.
+
+The **/Qspectre-load-cf** option is off by default, and supports all optimization levels.
+
+The **/Qspectre-load-cf** option is available in Visual Studio 2019 version 16.5 and later. This option is only available in compilers that target x86 and x64 processors. It's not available in compilers that target ARM processors.
+
+### To set this compiler option in the Visual Studio development environment
+
+1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md).
+
+2. Select the **Configuration Properties** > **C/C++** > **Code Generation** property page.
+
+3. Select a new value for the **Spectre Mitigation** property. Choose **OK** to apply the change.
+
+### To set this compiler option programmatically
+
+- See <xref:Microsoft.VisualStudio.VCProjectEngine.VCCLCompilerTool.AdditionalOptions%2A>.
+
+## See also
+
+[/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)

docs/build/reference/qspectre-load.md

@@ -0,0 +1,48 @@
+---
+title: "/Qspectre-load"
+description: "Describes the Microsoft C/C++ compiler (MSVC) /Qspectre-load option."
+ms.date: "01/28/2020"
+helpviewer_keywords: ["/Qspectre-load"]
+---
+# /Qspectre-load
+
+Specifies compiler generation of serializing instructions for every load instruction. This option extends the **/Qspectre** flag, mitigating against any possible **speculative execution side-channel attacks** based on loads.
+
+## Syntax
+
+> **/Qspectre-load**
+
+## 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:
+
+```asm
+    xor rbx, [rax]
+    xor rbx, [rax]  ; force a load of [rax]
+    lfence          ; followed by an LFENCE
+    jmp [rax]
+```
+
+Because **/Qspectre-load** stops speculation of all loads, the performance impact is high. The mitigation isn't appropriate everywhere. If there are performance critical blocks of code that don't require protection, you can disable these mitigations by using `__declspec(spectre(nomitigation))`. For more information, see [__declspec spectre](../../cpp/spectre.md).
+
+The **/Qspectre-load** option is off by default, and supports all optimization levels.
+
+The **/Qspectre-load** option is available in Visual Studio 2019 version 16.5 and later. This option is only available in compilers that target x86 and x64 processors. It's not available in compilers that target ARM processors.
+
+### To set this compiler option in the Visual Studio development environment
+
+1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md).
+
+2. Select the **Configuration Properties** > **C/C++** > **Code Generation** property page.
+
+3. Select a new value for the **Spectre Mitigation** property. Choose **OK** to apply the change.
+
+### To set this compiler option programmatically
+
+- See <xref:Microsoft.VisualStudio.VCProjectEngine.VCCLCompilerTool.AdditionalOptions%2A>.
+
+## See also
+
+[/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)

docs/toc.yml

@@ -702,6 +702,10 @@
                           href: build/reference/qsafe-fp-loads.md
                         - name: /Qspectre
                           href: build/reference/qspectre.md
+                        - name: /Qspectre-load
+                          href: build/reference/qspectre-load.md
+                        - name: /Qspectre-load-cf
+                          href: build/reference/qspectre-load-cf.md
                         - name: /Qvec-report (Auto-vectorizer reporting level)
                           href: build/reference/qvec-report-auto-vectorizer-reporting-level.md
                     - name: /RTC (Run-time error checks)