Merge pull request #25123 from johnno1962/reg-docco

Document ABI registers

Author: jckarter

docs/CallingConvention.rst renamed to docs/ABI/CallingConvention.rst

@@ -0,0 +1,13 @@
+## 64-Bit Architecture Register Usage
+
+From Swift 5, the calling convention register allocation for 64-bit architectures is largely based on [existing](https://developer.apple.com/library/content/documentation/Xcode/Conceptual/iPhoneOSABIReference/Articles/ARM64FunctionCallingConventions.html) [standards](https://developer.apple.com/library/content/documentation/DeveloperTools/Conceptual/LowLevelABI/140-x86-64_Function_Calling_Conventions/x86_64.html), with the addition of the context and error return registers discussed in the [ABI stability manifesto](https://github.com/apple/swift/blob/master/docs/ABIStabilityManifesto.md):
+
+| Register Purpose | ARM64 | x86_64 |
+| ------------- |:-------------:| ----- |
+| Context register (self) | x20 | r13 |
+| Error return register | x21 | r12 |
+| Struct return pointer | x8 | rax |
+| Float call arguments | v0 … v7 | xmm0 … xmm7 |
+| Integer call arguments | x0 … x7 | rdi, rsi, rdx, rcx, r8, r9 |
+| Float return | v0 … v3 | xmm0 … xmm3 |
+| Integer return | x0 … x3 | rax, rdx, rcx, r8 |

docs/ABI/RegisterUsage.md

@@ -337,6 +337,8 @@ Having the call context register be callee-saved is advantageous. It keeps the r
 
 Throwing functions communicate error values to their callers through the *error* register on some platforms. The error register holds a pointer to the error value if an error occurred, otherwise 0. The caller of a throwing function is expected to quickly check for 0 before continuing on with non-error code, otherwise branching to code to handle or propagate the error. Using a callee-saved register for the error register enables free conversion from non-throwing to throwing functions, which is required to honor the subtyping relationship.
 
+The specific registers used in these roles are documented in [another document on register usage](https://github.com/apple/swift/blob/master/docs/ABI/RegisterUsage.md).
+
 ### <a name="function-signature-lowering"></a>Function Signature Lowering
 
 Function signature lowering is the mapping of a function's source-language type, which includes formal parameters and results, all the way down to a physical convention, which dictates what values are stored in what registers and what values to pass on the stack.