Repo sync for protected CLA branch

docs/assembler/masm/instruction-format.md

@@ -0,0 +1,79 @@
+---
+description: Learn how instructions are formatted for translation by MASM.
+title: "MASM instruction format"
+ms.date: 09/21/2021
+helpviewer_keywords: ["MASM (Microsoft Macro Assembler), instruction reference", "instruction format", "instructions [MASM]"]
+no-loc: ["VEX", "REP"]
+---
+# MASM instruction format
+
+## Syntax
+
+Instructions are written in source code according to this syntax:
+
+> [*prefix*](#prefix)  [*mnemonic*](#mnemonic)  [*operand-list*](#operand-list)
+
+For information on instruction definitions, options, and encoding, see the [Processor Manufacturer Programming Manuals](../../assembler/masm/processor-manufacturer-programming-manuals.md). Some instructions and instruction options may not be supported by the Microsoft Macro Assembler.
+
+## Prefix
+
+You can prefix some instructions with keywords that set options for how the instruction is encoded. The **`REP`**, **`REPE`**, **`REPZ`**, **`REPNE`**, and **`REPNZ`** keywords are used with string instructions to do `memcpy` or `strlen` kinds of operations in a single instruction. The **`LOCK`** keyword makes certain operations on memory operands atomic. You can combine it with the **`XACQUIRE`** and **`XRELEASE`** keywords to do Hardware Lock Elision (HLE) on supported processors, which allows greater transactional parallelism in certain cases.
+
+The remaining prefixes control how AVX instructions are encoded. AVX instructions are encoded using a **`VEX`** prefix, which appears before the opcode. It takes the place of certain byte instruction prefixes and opcode lead-in bytes. Many AVX instructions are also AVX-512 instructions, which are encoded using an **`EVEX`** prefix that supports [more options](#avx-512-options). MASM tries to encode instructions as compactly as possible, but these keywords allow more control over which encoding to use with a particular instruction. They're also used to force generation of AVX instruction forms that were introduced after the corresponding AVX-512 instruction. For example, `vex vpdpbusd` specifies the AVX-VNNI form of the `VPDPBUSD` instructions rather than the AVX512-VNNI form. When an AVX instruction appears without an explicit prefix keyword, the encoding chosen depends on the current AVX encoding setting. The [`OPTION AVXENCODING`](option-avxencoding-masm.md) directive lets you change this setting.
+
+The **`VEX2`**, **`VEX3`**, **`VEX`**, and **`EVEX`** options are available in Visual Studio 2019 version 16.7 and later.
+
+| Keyword | Usage |
+|--|--|
+| **`REP`** | Repeat the string operation by the count in (E)CX. |
+| **`REPE`** | Repeat the string operation while the comparison is equal, limited by the count in (E)CX. |
+| **`REPE`** | Repeat the string operation while the comparison is not-equal, limited by the count in (E)CX. |
+| **`LOCK`** | Perform the operation atomically on a memory operand. |
+| **`XACQUIRE`** | Begin an HLE transaction, most often used with **`LOCK`** prefix. |
+| **`XRELEASE`** | Complete an HLE transaction, most often used with **`LOCK`** prefix. |
+| **`VEX`** | Encode an AVX instruction using a **`VEX`** prefix. |
+| **`VEX2`** | Encode an AVX instruction using a 2-byte **`VEX`** prefix. |
+| **`VEX3`** | Encode an AVX instruction using a 3-byte **`VEX`** prefix. |
+| **`EVEX`** | Encode an AVX instruction using an **`EVEX`** prefix. |
+
+## Mnemonic
+
+The mnemonic identifies a particular instruction, which determines the prefixes and operand patterns that are allowed.
+
+## Operand list
+
+Most instructions use an operand list to specify the explicit source and destination operands to the instruction. The operand list may contain memory references, registers, and constant values. Each instruction allows only certain types of operands to appear at each position in the operand list. Except for the `MOVS` and `CMPS` instructions, only one of the operands may be a memory reference; all other operands must be register references or constants.
+
+## AVX-512 options
+
+Some AVX-512 instructions allow more options to be specified. These options are: masking, zero-masking, embedded broadcast, embedded rounding, and exception suppression.
+
+*Masking* allows an operation to be applied only to selected elements of a vector. This option is controlled by placing a mask register from `{k1}` to `{k7}` after the destination operand. If the mask register is followed by `{z}`, all non-selected elements of the destination are set to zero. This alternative is known as *zero-masking*.
+
+*Embedded Broadcast* allows a scalar value in memory to be applied to all elements of a vector. This option is enabled by adding the element size and the keyword `BCST` to the memory operand, which is similar to the use of `PTR` for normal memory references.
+
+*Embedded Rounding* controls the rounding mode for an individual floating-point instruction, without having to set and reset the global rounding mode. It's enabled by following the instruction with the rounding mode enclosed in braces. When enabled, it also suppresses all exceptions for only that instruction. Floating-point instructions that don't round can also suppress all exceptions using a similar option.
+
+```asm
+  ; Examples of AVX-512 options
+  vaddps xmm1 {k1}, xmm2, xmm3            ; merge-masking
+  vsubps ymm0 {k4}{z}, ymm1, ymm2         ; zero-masking
+  vmulps zmm0, zmm1, dword bcst scalar    ; embedded broadcast
+  vdivps zmm0, zmm1, zmm2 {rz-sae}        ; embedded rounding
+  vmaxss xmm1, xmm2, xmm3 {sae}           ; suppress all exceptions
+```
+
+### Rounding modes
+
+| Mode | Effect |
+|--|--|
+| **`rn-sae`** | Round to nearest, ties to even, suppress all exceptions. |
+| **`rz-sae`** | Round toward zero, suppress all exceptions. |
+| **`rd-sae`** | Round down (toward negative infinity), suppress all exceptions. |
+| **`ru-sae`** | Round up (toward positive infinity), suppress all exceptions. |
+| **`sae`** | Suppress all exceptions (no rounding needed). |
+
+## See also
+
+[Microsoft Macro Assembler Reference](microsoft-macro-assembler-reference.md)<br/>
+[Processor Manufacturer Programming Manuals](../../assembler/masm/processor-manufacturer-programming-manuals.md)<br/>

docs/assembler/masm/masm-for-x64-ml64-exe.md

@@ -1,23 +1,23 @@
 ---
-description: "Learn more about: MASM for x64 (ml64.exe)"
+description: "Learn more about: Microsoft Macro Assembler (MASM) for x64 (ml64.exe)"
 title: "MASM for x64 (ml64.exe)"
-ms.date: "12/17/2019"
+ms.date: 09/21/2021
 helpviewer_keywords: ["ml64", "ml64.exe", "masm for x64"]
 ms.assetid: 89059103-f372-4968-80ea-0c7f90bb9c91
 ---
 # MASM for x64 (ml64.exe)
 
-Visual Studio includes both 32-bit and 64-bit hosted versions of Microsoft Assembler (MASM) to target x64 code. Named ml64.exe, this is the assembler that accepts x64 assembler language. The MASM command-line tools are installed when you choose a C++ workload during Visual Studio installation. The MASM tools are not available as a separate download. For instructions on how to download and install a copy of Visual Studio, see [Install Visual Studio](/visualstudio/install/install-visual-studio). If you do not want to install the complete Visual Studio IDE, but only want the command-line tools, download the [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019).
+Visual Studio includes both 32-bit and 64-bit hosted versions of MASM (the Microsoft Macro Assembler) to target x64 code. Named ml64.exe, it's the assembler that accepts x64 assembler language. The MASM command-line tools are installed when you choose a C++ workload during Visual Studio installation. The MASM tools aren't available as a separate download. For instructions on how to download and install a copy of Visual Studio, see [Install Visual Studio](/visualstudio/install/install-visual-studio). If you only want the command-line tools, not the full IDE, download the [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019).
 
-To use MASM to build code for x64 targets on the command line, you must use a developer command prompt for x64 targets, which sets the required path and other environment variables. For information on how to start a developer command prompt, see [Build C/C++ code on the command line](../../build/building-on-the-command-line.md).
+To use ml64.exe on the command line, start a developer command prompt for x64 targets. A developer command prompt sets the required path and other environment variables. For information on how to start a developer command prompt, see [Build C/C++ code on the command line](../../build/building-on-the-command-line.md).
 
-For information on ml64.exe command line options, see [ML and ML64 Command-Line Reference](ml-and-ml64-command-line-reference.md).
+For information on ml64.exe command-line options, see [ML and ML64 Command-Line Reference](ml-and-ml64-command-line-reference.md).
 
-Inline assembler or use of the ASM keyword is not supported for x64 or ARM targets. To port your x86 code that uses inline assembler to x64 or ARM, you can convert your code to C++, use compiler intrinsics, or create assembler-language source files. The Microsoft C++ compiler supports intrinsics to allow you to use special-function instructions, for example, privileged, bit scan/test, interlocked, and so on, in as close to a cross-platform manner as possible. For information on available intrinsics, see [Compiler Intrinsics](../../intrinsics/compiler-intrinsics.md).
+Inline assembler or use of the **`ASM`** keyword isn't supported for x64 or ARM64 targets. To port your x86 code that uses inline assembler to x64 or ARM64, you can convert your code to C++, use compiler intrinsics, or create assembler-language source files. The Microsoft C++ compiler supports intrinsics to allow you to use special-function instructions, for example, privileged, bit scan or test, interlocked, and so on, in as close to a cross-platform manner as possible. For information on available intrinsics, see [Compiler Intrinsics](../../intrinsics/compiler-intrinsics.md).
 
 ## Add an assembler-language file to a Visual Studio C++ project
 
-The Visual Studio project system supports assembler-language files built by using MASM in your C++ projects. You can create x64 assembler-language source files and build them into object files by using MASM, which supports x64 fully. You can then link these object files to your C++ code built for x64 targets. This is one way to overcome the lack of an x64 inline assembler.
+The Visual Studio project system supports assembler-language files built by using MASM in your C++ projects. MASM fully supports x64 assembler-language source files, and builds them into object files. You can then link these object files to your C++ code built for x64 targets. It's one way to overcome the lack of an x64 inline assembler.
 
 ### To add an assembler-language file to an existing Visual Studio C++ project
 
@@ -27,29 +27,29 @@ The Visual Studio project system supports assembler-language files built by usin
 
 1. On the menu bar, choose **Project**, **Add New Item**.
 
-1. In the **Add New Item** dialog box, select **C++ file (.cpp)** in the center pane. In the **Name** edit control, enter a new file name that has a **.asm** extension instead of .cpp. Choose **Add** to add the file to your project and close the dialog box.
+1. In the **Add New Item** dialog box, select **C++ file (.cpp)** in the center pane. In the **Name** edit control, enter a new file name that has a *`.asm`* extension instead of *`.cpp`*. Choose **Add** to add the file to your project and close the dialog box.
 
-Create your assembler-language code in the .asm file you added. When you build your solution, the MASM assembler is invoked to assemble the .asm file into an object file that is then linked into your project. To make symbol access easier, declare your assembler functions as `extern "C"` in your C++ source code, rather than using the C++ name decoration conventions in your assembler-language source files.
+Create your assembler-language code in the *`.asm`* file you added. When you build your solution, the MASM assembler is invoked to assemble the *`.asm`* file into an object file that is then linked into your project. To make symbol access easier, declare your assembler functions as `extern "C"` in your C++ source code, rather than using the C++ name decoration conventions in your assembler-language source files.
 
 ## ml64-Specific Directives
 
 You can use the following ml64-specific directives in your assembler-language source code that targets x64:
 
-- [.ALLOCSTACK](dot-allocstack.md)
+- [`.ALLOCSTACK`](dot-allocstack.md)
 
-- [.ENDPROLOG](dot-endprolog.md)
+- [`.ENDPROLOG`](dot-endprolog.md)
 
-- [.PUSHFRAME](dot-pushframe.md)
+- [`.PUSHFRAME`](dot-pushframe.md)
 
-- [.PUSHREG](dot-pushreg.md)
+- [`.PUSHREG`](dot-pushreg.md)
 
-- [.SAVEREG](dot-savereg.md)
+- [`.SAVEREG`](dot-savereg.md)
 
-- [.SAVEXMM128](dot-savexmm128.md)
+- [`.SAVEXMM128`](dot-savexmm128.md)
 
-- [.SETFRAME](dot-setframe.md)
+- [`.SETFRAME`](dot-setframe.md)
 
-In addition, the [PROC](proc.md) directive has been updated for use with ml64.exe.
+The [`PROC`](proc.md) directive has also been updated for use with ml64.exe.
 
 ## 32-Bit Address Mode (Address Size Override)
 
@@ -63,7 +63,7 @@ prefetch [eax]
 movnti rax, QWORD PTR [r8d]
 ```
 
-MASM assumes that if a 32-bit displacement appears alone as a memory operand, 64-bit addressing is intended. There is currently no support for 32-bit addressing with such operands.
+MASM assumes 64-bit addressing if a 32-bit displacement appears alone as a memory operand. There's currently no support for 32-bit addressing with such operands.
 
 Finally, mixing register sizes within a memory operand, as demonstrated in the following code, generates an error.
 

docs/assembler/masm/microsoft-macro-assembler-reference.md

@@ -1,21 +1,23 @@
 ---
 description: "Learn more about: Microsoft Macro Assembler reference"
 title: "Microsoft Macro Assembler reference"
-ms.date: "12/17/2019"
+ms.date: 09/21/2021
 helpviewer_keywords: ["MASM (Microsoft Macro Assembler), reference", "MASM (Microsoft Macro Assembler), overview", "MASM (Microsoft Macro Assembler)", "MASM (Microsoft Macro Assembler), documentation overview"]
-ms.assetid: 1446d55f-e2e7-4fd1-a9b8-b15cf7d4e47c
 ---
 # Microsoft Macro Assembler reference
 
-The Microsoft Macro Assembler (MASM) provides several advantages over inline assembly. MASM contains a macro language that has features such as looping, arithmetic, and text string processing. MASM also gives you greater control over the hardware because it supports the instruction sets of the 386, 486, and Pentium processors. By using MASM, you also can reduce time and memory overhead.
+The Microsoft Macro Assembler (MASM) provides several advantages over inline assembly. MASM contains a macro language that has features such as looping, arithmetic, and text string processing. MASM gives you greater control over the hardware. By using MASM, you also can reduce time and memory overhead in your code.
 
 ## In This Section
 
 [ML and ML64 command-line option](ml-and-ml64-command-line-reference.md)\
-Describes the ML.exe and ML64.exe command-line options.
+Describes the ML and ML64 command-line options.
 
-[ML error messages](ml-error-messages.md)\
-Describes ML.exe fatal and nonfatal error messages and warnings.
+[MASM for x64 (ml64.exe)](masm-for-x64-ml64-exe.md)\
+Information about how to create output files for x64.
+
+[Instruction Format](instruction-format.md)\
+Describes basic instruction format and instruction prefixes for MASM.
 
 [Directives reference](directives-reference.md)\
 Provides links to articles that discuss the use of directives in MASM.
@@ -26,11 +28,11 @@ Provides links to articles that discuss the use of symbols in MASM.
 [Operators Reference](operators-reference.md)\
 Provides links to articles that discuss the use of operators in MASM.
 
-[Processor Manufacturer Programming Manuals](processor-manufacturer-programming-manuals.md)\
-Provides links to websites that may contain programming information about processors that are not manufactured, sold, or supported by Microsoft.
+[ML error messages](ml-error-messages.md)\
+Describes fatal and nonfatal error messages and warnings.
 
-[MASM for x64 (ml64.exe)](masm-for-x64-ml64-exe.md)\
-Information about how to create output files for x64.
+[Processor Manufacturer Programming Manuals](processor-manufacturer-programming-manuals.md)\
+Provides links to programming information about processors not manufactured, sold, or supported by Microsoft.
 
 [MASM BNF Grammar](masm-bnf-grammar.md)
 
@@ -44,5 +46,5 @@ Provides links to different areas of the Visual Studio and Visual C++ documentat
 ## See also
 
 [Compiler Intrinsics](../../intrinsics/compiler-intrinsics.md)\
-[x86Intrinsics](../../intrinsics/x86-intrinsics-list.md)\
+[x86 Intrinsics](../../intrinsics/x86-intrinsics-list.md)\
 [x64 (amd64) Intrinsics](../../intrinsics/x64-amd64-intrinsics-list.md)