cmd/compile: switch to a register-based calling convention for Go functions

[aclements]

I propose that we switch the Go internal ABI (used between Go functions) from stack-based to register-based argument and result passing for Go 1.16 1.17.

I lay out the details of our proposal and the work required in this document.

The ABI specification can be found here.

This was previously proposed in #18597, where @dr2chase did some excellent prototyping work that our new proposal builds on. With multiple ABI support, we’re now in a much better position to execute on this without breaking compatibility with the existing body of Go assembly code. I’ve opened this new issue to focus on discussion of our new proposal.

/cc @dr2chase @danscales @thanm @cherrymui @mknyszek @prattmic @randall77

An incomplete and evolving list of tasks:

• Define ABI specification (CL, @aclements)
• Add GOEXPERIMENT=regabi and asm macro (CL)
• cmd/compile: late call lowering (CLs)
• cmd/compile: implement register arguments (@dr2chase)
  • spill around morestack call (CL)
  • add temporary ABI pragma for testing (CL)
  • add abstract argument registers (WIP CL)
  • implement ABI rules (CL)
  • use abstract argument registers
• cmd/compile: implement register returns
  • late return lowering (CL, @dr2chase)
  • implement ABI rules (CL, @thanm)
• cmd/compile: ABI wrappers (CL, old CL)
  • cmd/link: mangle wrapper names for ELF (CL)
  • cmd/link: mangle wrapper names for PE (CL)
  • implement zeroing of X15 in ABI0->ABIInternal wrappers (CL)
• cmd/asm: add syntax for runtime packages to reference ABIInternal symbols (CL)
  • Mark runtime.{goexit,asyncPreempt}, reflect.{makeFuncStub,methodValueCall} definitions ABIInternal (CL)
  • Mark reference to runtime.callbackWrap in sys_windows_amd64.s as ABIInternal (CL)
• runtime: fix assembly closure calls (mcall) (@aclements, CL)
• reflect: support calling ABIInternal (CL)
• reflect: support MakeFunc and method value calls (CL)
• go and defer statements
  • cmd/compile: desugar go/defer to zero-argument (@thanm, CL)
  • cmd/compile: fix defer recover() (@cherrymui, CL)
  • cmd/compile: desugar go/defer with results (@cherrymui, CL)
• cmd/cgo: decouple cgo callbacks from ABI (CL)
• runtime: finalizer support (CL)
• runtime: Windows callback support (CL)
• cmd/internal/obj: introduce and use RegEntryTmp registers in prologue (@mknyszek, CL)
• cmd/compile: generate correct ABI0 argument maps for body-less functions (see WriteFuncMap) (@dr2chase, CL)
• cmd/compile: make cgo_unsafe_args generate an ABI0 function (or an ABIInternal-with-no-registers function) (@cherrymui, CL)
• runtime: update debug call protocol (CL)
• Fix ABI0/ABIInternal confusion in cgo (CL)
• Run signature fuzzer and fix bugs (everyone)
• Get all.bash to pass on Linux, Windows, and Darwin (everyone)

High-priority non-critical path

• Export ABI information across package boundaries to eliminate more wrappers (@aclements, CL)
• Make funcPC always return the "native" PC of a function (maybe also introduce ABIOther) (@cherrymui, CL)
• Strip unnecessary ABIInternal annotations once funcPC is in
• Tracebacks
  • Define extended argument metadata format (in progress, @cherrymui)
  • cmd/compile: produce extended argument metadata (@cherrymui, CL)
  • runtime: consume extended argument metadata (@cherrymui, CL)
  • cmd/compile,runtime: traceback metadata for spill slot liveness
• DWARF
  • cmd/compile: ensure arguments have appropriate DWARF locations
  • Ensure GDB and Delve can find register arguments
  • [ ] cmd/compile: add a DWARF vendor attribute with function argument frame size (context)
• Wrapper mangling for non-critical arches
  • cmd/link: mangle wrapper names for Mach-O (CL)
  • cmd/link: mangle wrapper names for xcoff
  • cmd/link: mangle wrapper names for Plan 9
• runtime: simplify go/defer call paths
  • assert that go/defer frames are zero sized (CL)
  • replace defer reflectcall with a direct closure call (CL)
• cmd/internal/obj: reject splittable ABIInternal functions without morestack spill info (e.g., asm functions) because we can't generate a correct morestack path (CL)
• cmd/asm: don't reference args_stackmap in ABIInternal functions (because it's for ABI0) (CL)
• Port performance-critical assembly to ABIInternal (see CL 296372 for valuable functions) (CL 308931, CL 310184)
• math: fix overhead of assembly->Go calls CL 310331
• Release notes
  • Mention undocumented behavior we've observed applications depending on that may have changed.
    • Using reflect.ValueOf(fn).Pointer() to get the PC of an assembly function will now return the PC of the ABI wrapper
  • Performance surprise: calling from assembly to Go is slightly more expensive.
  • Performance surprise: calling an assembly function via a closure is slightly more expensive.
  • Traceback format is much improved

Enabling steps

• Enable regabiwrappers by default on amd64 (Linux, Windows, and Darwin)
• Enable regabidefer
• Enable regabireflect
• Enable regabig
• Enable regabiargs

Testing

• Function signature fuzzer (ongoing)
  • Static call, closure call, method call, interface call, reflect.{ValueOf(target),MakeFunc(x, target),Method(x)}.{Call,Interface}, called from defer, called from go, called as a finalizer
  • {Big,Small} {argument,result} in {memory,registers} and {not addressed,addressed and not leaked to heap,addressed and leaked to heap}
  • Use defer in a test function (check arguments, modify results)
  • Pass pointers-to-stack and pointers-to-heap
  • Cause result to move to heap
  • runtime: add MoveStackOnNextCall, assertions for pointer-to-stack/pointer-to-heap, assertions for live/dead (@aclements, CL)
  • Integrate runtime testing hook
  • Clean up fuzzer, and get into tools repo.
• cmd/compile: revive clobberdead (CL)
• cmd/compile: add clobberdeadreg (CL)

Post-MVP

• Move g from TLS to register (CL)
  • Use g register on non-Linux OSes (see CL)
• Reserve and use X15 as zero register (CL)
  • [ ] Should this be X0 for more compact instruction encoding?
• Port to other platforms
  • amd64
  • arm64
  • mips
  • ppc
  • s390x
  • risc-v
  • [ ] porting guide
• Eliminate legacy ABI paths for all platforms, even if they're using ABIInternal with 0 registers
• Eliminate spill slots?
• Pass pointer-shaped method receiver in context register (cmd/compile: pass pointer-shaped receivers using context register #44827)
• runtime: simplify go/defer call paths
  • simplify go/defer paths to assume zero args/results
  • simplify special _defer allocator and remove special _defer cases from mallocgc (because _defer records will be fixed size).
• cmd/vet: add syntax and checks for register arguments and results in assembly like x+0(FP)
• cmd/vet: check argument size for ABIInternal functions and fix runtime asm declarations

Cleanup (can be done later)

• runtime: port all assembly -> Go calls to ABIInternal?
• Eliminate ABIAlias support from cmd/compile, cmd/link, and object format
• remove now-redundant fields from ssa.AuxCall
• rationalize use of LocalsOffset/FrameOffset (for registers that use a link register, e.g. arm64, powerppc).
• cmd/compile: revisit abiutils.go and clean up the API (also reduce ABIConfig copying)
• cmd/internal/obj: generate stack maps in obj so we can better compact the morestack/body maps and reduce subtlety?
• cmd/compile,runtime: re-enable passing arguments to go in runtime (context)
• cmd/compile: always attach ir.Func to function ir.Names (context)
• cmd/compile: support ABIInternal for tail calls (context)
• cmd/compile: once wrapping of defers is on for all arch/OS combinations, it should be possible to simplify or remove some of the openDefer processing in ssagen (notablly we could get rid of openDeferSave()
• [ ] runtime: think about an ABI-insensitive debugCall Delve uses DWARF information
• Fix up named slots & value association
• fix firstpos in ssa.go – sometimes it's late.

[seebs]

Once upon a time, I was one of several people whose primary work activity for I think two days was tracking down a weird kernel crash, which was ultimately caused by callee-saved registers. Well, the crash was caused by a [FOO_MAX] array being overrun. But the thing where the result of that overrun was to overwrite a single automatic variable, which never had its address taken, five call frames away? That was caused by callee-saved registers.

Which is to say:

Platform ABIs typically define callee-save registers, which place substantial additional requirements on a garbage collector. There are alternatives to callee-save registers that share many of their benefits, while being much better suited to Go.

+1 +1 +1 +1 +1 +1 [...]

[ncw]

If I'm understanding the proposal correctly, assembler code will continue to be written with the current stack based calling conventions.

I understand the excellent reasoning behind doing this, I'll just note that this is surely going to frustrate assembly code writers not being able to pass and receive args in registers as often assembly code fragments are tiny and the overhead of calling them is massive.

[mknyszek]

@ncw This restriction to ABI0 for assembly writers isn't necessarily permanent. See https://go.googlesource.com/proposal/+/master/design/27539-internal-abi.md#proposal.

[laboger]

Right now writeBarrier is a special builtin that allows arguments to be passed in registers. Couldn't that same concept be extended to others like memmove and memcpy to avoid call overhead even though they are asm?

[aclements]

@laboger , yes, we're considering special-casing just a few assembly functions. The hottest ones by far are memmove, memclrNoHeapPointers, and possibly syscall.Syscall. The write barrier calling convention is very specialized because its context is so unusual and performance-sensitive. We'll probably just switch the others to use the register ABI rather than anything more specialized (and teach the toolchain that those are special even though they're assembly).

[mknyszek]

A comment on the "stack growth" section of the doc, specifically about spilling register state for morestack into the guard space for a goroutine (copied from Gerrit):

I worry a little bit about cases where functions marked nosplit eventually call into a non-nosplit function. If the nosplit frames are large (but don't exceed the guard space) we might find out that we don't have any space left. What should we do in this case? Throwing doesn't seem quite right since this works just fine today (though, you have to be careful). Should we have "guard space" and a subset of that as "no, really, this is very guarded" space? That would require extending the guard space a bit further which isn't great...

One alternative is to manage per-goroutine space for this, but that's not great either, since its more memory used per goroutine.

[cherrymui]

Good point. This is especially true for architectures that have a lot registers. Maybe we could decide that some registers are never live across a call?

[aclements]

That's an excellent point. A few possible solutions come to mind:

1. It would be really sad if we had to make more per-goroutine space for this since you almost always have space on the stack. One possibility is to spill to the stack if there's room, and otherwise we keep a pool of allocated "spill space" objects. For that, we could keep just one pre-allocated per P and if the goroutine needs it, it can pull it off the P, spill into it, and then once it's entered the runtime it can allocate a new one (probably getting it from a global allocation pool) and attach it to the P. On return, it can return it to the allocation pool.

2. A similar option would be to have just one spill space per P. Again, use the stack if you can, otherwise spill into the P, enter the runtime, grow the stack even if it's just a preemption, and then dump the spilled registers back onto the stack in the right place.

3. We could revisit the nosplit rules. It's often (though not always) a mistake to call from a nosplit function to a non-nosplit function. I'm not sure exactly what this would look like. Maybe a non-nosplit function called from a nosplit function has to have a special prologue? Related: cmd/compile, runtime: add and use go:nosplitrec compilation directive #21314 (comment). I think the only cases I enumerated in that comment that intentionally call from a nosplit to a non-nosplit function aren't running on a user G stack and thus can't grow it anyway.

[gopherbot]

Change https://golang.org/cl/252258 mentions this issue: cmd/asm: define a macro for GOEXPERIMENT=regabi

[gopherbot]

Change https://golang.org/cl/252257 mentions this issue: cmd/internal/objabi: add regabi GOEXPERIMENT

[gopherbot]

Change https://golang.org/cl/258938 mentions this issue: runtime,cmd/cgo: simplify C -> Go call path

[aclements]

@alexbrainman , I just ran into a bit of a snag on Windows that maybe you can better inform me on. It looks like syscall.NewCallback is going to also need an implementation of the Go internal ABI rules and I'm trying to figure out exactly what that needs to look like. (I pinged you because it looks like you last substantially touched that code, but feel free to pass the ping.)

The documentation says "The argument is expected to be a function with one uintptr-sized result. The function must not have arguments with size larger than the size of uintptr." Does this actually mean the arguments (and result) must be an integral, floating-point, or pointer type? Or does it mean, say, struct { x, y uint16 } or struct { x [4]byte } is allowed, since those are technically no larger than the size of a uintptr? The current implementation permits the latter, though I don't know if it actually works.

If they must be int/float/pointer, then mapping from the Windows ABI to the Go register ABI is relatively straightforward. If compounds are allowed, then this gets much harder.

[networkimprov]

cc @jstarks re the ABI question.

[alexbrainman]

@aclements I reckon there are very few instances of syscall.NewCallback usage. But they are used a lot.

If you want to build Windows GUI, you have to use syscall.NewCallback, because Windows GUI API requires syscall.NewCallback.

Similarly, if you want to build Windows service, you have to use syscall.NewCallback.

These two pretty much cover syscall.NewCallback usage.

For Windows service, you can look in golang.org/x/sys/windows/svc. It uses this RegisterServiceCtrlHandlerEx WIndows API

https://docs.microsoft.com/en-us/windows/win32/api/winsvc/nf-winsvc-registerservicectrlhandlerexw

which requires LPHANDLER_FUNCTION_EX

https://docs.microsoft.com/en-us/windows/win32/api/winsvc/nc-winsvc-lphandler_function_ex

so LPHANDLER_FUNCTION_EX returns DWORD (uint32).

For GUI grep in golang.org/x/exp/shiny - it uses RegisterClass

https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-registerclassw

which uses WNDCLASSW.lpfnWndProc

https://docs.microsoft.com/en-us/windows/win32/api/winuser/ns-winuser-wndclassw

which is WNDPROC

https://docs.microsoft.com/en-us/previous-versions/windows/desktop/legacy/ms633573(v=vs.85)

which returns LRESULT which is LONG_PTR or uintptr (in Go)

https://docs.microsoft.com/en-us/windows/win32/winprog/windows-data-types

Also I recommend you look at github.com/lxn/walk for their syscall.NewCallback usage. This is an ultimate package to create GUI apps. But, I doubt, you will find different usage than golang.org/x/exp/shine. (I did not look myself)

I reckon, that is about it. For Microsoft APIs (maybe google code for syscall.NewCallback or windows.NewCallback).

But some people might use it in their custom / proprietary interface. I am not sure how these are supported by Go. You will be the judge.

Alex

[CAFxX]

IIUC this example in the microsoft docs shows that compounds are allowed:

struct Struct2 {
   int j, k;    // Struct2 fits in 64 bits, and meets requirements for return by value.
};
Struct2 func4(int a, double b, int c, float d);
// Caller passes a in RCX, b in XMM1, c in R8, and d in XMM3;
// callee returns Struct2 result by value in RAX.

[gopherbot]

Change https://golang.org/cl/262197 mentions this issue: go/analysis/passes/asmdecl: add support for ABI selector clauses

[gopherbot]

Change https://golang.org/cl/262319 mentions this issue: reflect,runtime: use internal ABI for selected ASM routines

[gopherbot]

Change https://golang.org/cl/262317 mentions this issue: cmd/dist,cmd/go: broaden use of asm macro GOEXPERIMENT_REGABI

[gopherbot]

Change https://golang.org/cl/259445 mentions this issue: cmd/compile,cmd/link: initial support for ABI wrappers

[gopherbot]

Change https://golang.org/cl/260477 mentions this issue: cmd/asm: allow def/ref of func ABI when compiling runtime

[gopherbot]

Change https://golang.org/cl/262318 mentions this issue: cmd: go get golang.org/x/tools@d1624618 && go mod vendor

[gopherbot]

Change https://golang.org/cl/262117 mentions this issue: cmd/compile: delay expansion of OpArg until expand_calls

[gopherbot]

Change https://go.dev/cl/521779 mentions this issue: cmd/compile/internal: add register info for loong64 regABI

[gopherbot]

Change https://go.dev/cl/521783 mentions this issue: runtime: support regABI and add spill functions in runtime for loong64

[gopherbot]

Change https://go.dev/cl/521787 mentions this issue: cmd/internal/obj: set morestack arg spilling and regabi prologue on loong64

[gopherbot]

Change https://go.dev/cl/521778 mentions this issue: internal/abi: define loong64 regABI constants

[gopherbot]

Change https://go.dev/cl/521777 mentions this issue: cmd/compile,cmd/internal,runtime: change registers on loong64 to avoid regABI arguments

[gopherbot]

Change https://go.dev/cl/521775 mentions this issue: cmd/compile, cmd/internal, runtime: change the registers used by the duff device for loong64

[gopherbot]

Change https://go.dev/cl/521785 mentions this issue: internal/bytealg: add regABI support in bytealg functions on loong64

[gopherbot]

Change https://go.dev/cl/521782 mentions this issue: runtime: make duff device as ABIInternal for loong64

[gopherbot]

Change https://go.dev/cl/521780 mentions this issue: cmd/compile/internal: add spill support for loong64 regABI

[gopherbot]

Change https://go.dev/cl/521784 mentions this issue: reflect, runtime: add reflect support for regABI on loong64

[gopherbot]

Change https://go.dev/cl/521789 mentions this issue: runtime/internal/syscall: use ABIInternal for Syscall6 on loong64

[gopherbot]

Change https://go.dev/cl/521776 mentions this issue: cmd/compile: add ABI register definations for loong64

[gopherbot]

Change https://go.dev/cl/521790 mentions this issue: cmd/compile, internal/buildcfg: enable regABI on loong64, and add loong64 in test func hasRegisterABI