cmd/compile: document register-based ABI for s390x

This CL adds the s390x information to the ABI doc.

Update #40724

Cq-Include-Trybots: luci.golang.try:gotip-linux-s390x
Change-Id: I1b4b25ef1003e2ab011e1b808aeb1c02288095c2
Reviewed-on: https://go-review.googlesource.com/c/go/+/719460
Reviewed-by: Cherry Mui <cherryyz@google.com>
Reviewed-by: Vishwanatha HD <vishwanatha.hd@ibm.com>
TryBot-Bypass: David Chase <drchase@google.com>
Reviewed-by: Keith Randall <khr@golang.org>
Reviewed-by: Michael Pratt <mpratt@google.com>

diff --git a/src/cmd/compile/abi-internal.md b/src/cmd/compile/abi-internal.md
index eae230dc070d86964125ee2472f9850c091c4e4e..8de8356132ad14cc4cff0b2084371923af30082c 100644 (file)
--- a/src/cmd/compile/abi-internal.md
+++ b/src/cmd/compile/abi-internal.md
@@ -833,6 +833,51 @@ The riscv64 has Zicsr extension for control and status register (CSR) and
 treated as scratch register.
 All bits in CSR are system flags and are not modified by Go.
 
+### s390x architecture
+
+The s390x architecture uses R2 – R9 for integer arguments and integer results.
+
+It uses F0 – F15 for floating-point arguments and results.
+
+Special-purpose registers used within Go generated code and Go assembly code
+are as follows:
+
+| Register | Call meaning | Return meaning | Body meaning |
+| --- | --- | --- | --- |
+| R0 | Zero value | Same | Same |
+| R1 | Scratch | Scratch | Scratch |
+| R10, R11 | used by the assembler | Same | Same |
+| R12 | Closure context pointer | Same | Same |
+| R13 | Current goroutine | Same | Same |
+| R14 | Link register | Link register | Scratch |
+| R15 | Stack pointer | Same | Same |
+
+*Rationale*: These register meanings are compatible with Go’s stack-based
+calling convention.
+
+#### Stack layout
+
+The stack pointer, R15, grows down and is aligned to 8 bytes.
+
+A function's stack frame, after the frame is created, is laid out as
+follows:
+
+    +------------------------------+
+    | ... locals ...               |
+    | ... outgoing arguments ...   |
+    | return PC                    | ← R15 points to
+    +------------------------------+ ↓ lower addresses
+
+This stack layout is used by both register-based (ABIInternal) and
+stack-based (ABI0) calling conventions.
+
+The "return PC" is loaded to the link register R14, as part of the
+s390x `BL` operation.
+
+#### Flags
+The s390x architecture maintains a single condition code (CC) field in the Program Status Word (PSW).
+Go-generated code sets and tests this condition code to control conditional branches.
+
 ## Future directions
 
 ### Spill path improvements