5/29/2023 AM Publish (#4928)

* Volatile vs Non-volatile is a very Microsoft specific terminology. Out in the industry, register calling convention assignment are more frequently referred to as Caller vs Callee saved.

Also, x18 is a reserved register, so it is neither Caller nor Callee Saved.

* Add links to C28306 and C28307.

* Incorporate feedback: Restrict changes to the registers that previously had objectively incorrect descriptions.

* Push missing merge.

* Push missing merge.

* Fix description of paramter/result registers. x1, x8 and v1-v3 can also be result registers.

---------

Co-authored-by: Pedro Miguel Justo <[email protected]>
Co-authored-by: Michael Woerister <michaelwoerister@posteo>
Co-authored-by: learn-build-service-prod[bot] <113403604+learn-build-service-prod[bot]@users.noreply.github.com>
Co-authored-by: Pedro Justo <[email protected]>
Co-authored-by: Courtney Wales <[email protected]>
Co-authored-by: huypub <[email protected]>
Co-authored-by: prmerger-automator[bot] <40007230+prmerger-automator[bot]@users.noreply.github.com>

Author: 8 people

docs/build/arm64-windows-abi-conventions.md

@@ -66,16 +66,15 @@ Default layout alignment for globals and statics:
 
 The AArch64 architecture supports 32 integer registers:
 
-| Register | Volatile? | Role |
+| Register | Volatility | Role |
 | - | - | - |
-| x0 | Volatile | Parameter/scratch register 1, result register |
-| x1-x7 | Volatile | Parameter/scratch register 2-8 |
-| x8-x15 | Volatile | Scratch registers |
+| x0-x8 | Volatile | Parameter/Result scratch registers |
+| x9-x15 | Volatile | Scratch registers |
 | x16-x17 | Volatile | Intra-procedure-call scratch registers |
-| x18 | Non-volatile | Platform register: in kernel mode, points to KPCR for the current processor; in user mode, points to TEB |
+| x18 | N/A | Reserved platform register: in kernel mode, points to KPCR for the current processor; In user mode, points to TEB |
 | x19-x28 | Non-volatile | Scratch registers |
 | x29/fp | Non-volatile | Frame pointer |
-| x30/lr | Non-volatile | Link registers |
+| x30/lr | Both | Link Register: Callee function must preserve it for its own return, but caller's value will be lost. |
 
 Each register may be accessed as a full 64-bit value (via x0-x30) or as a 32-bit value (via w0-w30). 32-bit operations zero-extend their results up to 64 bits.
 
@@ -89,18 +88,17 @@ The frame pointer (x29) is required for compatibility with fast stack walking us
 
 The AArch64 architecture also supports 32 floating-point/SIMD registers, summarized below:
 
-| Register | Volatile? | Role |
+| Register | Volatility | Role |
 | - | - | - |
-| v0 | Volatile | Parameter/scratch register 1, result register |
-| v1-v7 | Volatile | Parameter/scratch registers 2-8 |
-| v8-v15 | Non-volatile | Scratch registers (only the low 64 bits are non-volatile) |
+| v0-v7 | Volatile | Parameter/Result scratch registers |
+| v8-v15 | Both | Low 64 bits are Non-Volatile. High 64 bits are Volatile. |
 | v16-v31 | Volatile | Scratch registers |
 
 Each register may be accessed as a full 128-bit value (via v0-v31 or q0-q31). It may be accessed as a 64-bit value (via d0-d31), as a 32-bit value (via s0-s31), as a 16-bit value (via h0-h31), or as an 8-bit value (via b0-b31). Accesses smaller than 128 bits only access the lower bits of the full 128-bit register. They leave the remaining bits untouched unless otherwise specified. (AArch64 is different from AArch32, where the smaller registers were packed on top of the larger registers.)
 
 The floating-point control register (FPCR) has certain requirements on the various bitfields within it:
 
-| Bits | Meaning | Volatile? | Role |
+| Bits | Meaning | Volatility | Role |
 | - | - | - | - |
 | 26 | AHP | Non-Volatile | Alternative half-precision control. |
 | 25 | DN | Non-Volatile | Default NaN mode control. |

docs/code-quality/c28306.md

@@ -11,3 +11,7 @@ ms.assetid: 64517b10-c8b3-4100-953b-278eab624369
 > The annotation on parameter is obsolescent
 
 Use `_String_length_` with the appropriate SAL2 annotation instead.
+
+## See also
+
+[Intrinsic Functions](./intrinsic-functions.md)

docs/code-quality/c28307.md

@@ -11,3 +11,7 @@ ms.assetid: e86a14cc-9ff1-4bad-9d85-93c739704ab8
 > The annotation on parameter is obsolescent
 
 Use `_String_length_` with the appropriate SAL2 annotation instead.
+
+## See also
+
+[Intrinsic Functions](./intrinsic-functions.md)