From f00fa0b98da9f4353839da99e6f6f7f109f9954f Mon Sep 17 00:00:00 2001 From: Austin Clements Date: Wed, 13 Jul 2022 13:36:23 -0400 Subject: [PATCH] runtime: document stkframe The meaning of some of the fields in stkframe is actually quite subtle. Change-Id: Iac765ff6fbf4c3b7c9f2453f5b4a2e5e640f5750 Reviewed-on: https://go-review.googlesource.com/c/go/+/424256 TryBot-Result: Gopher Robot Reviewed-by: Cherry Mui Run-TryBot: Austin Clements Reviewed-by: Michael Pratt Auto-Submit: Austin Clements --- src/runtime/runtime2.go | 59 +++++++++++++++++++++++++++++++++-------- 1 file changed, 48 insertions(+), 11 deletions(-) diff --git a/src/runtime/runtime2.go b/src/runtime/runtime2.go index c3cb392540..4e67fd6e44 100644 --- a/src/runtime/runtime2.go +++ b/src/runtime/runtime2.go @@ -985,18 +985,55 @@ type _panic struct { goexit bool } -// stack traces +// A stkframe holds information about a single physical stack frame. type stkframe struct { - fn funcInfo // function being run - pc uintptr // program counter within fn - continpc uintptr // program counter where execution can continue, or 0 if not - lr uintptr // program counter at caller aka link register - sp uintptr // stack pointer at pc - fp uintptr // stack pointer at caller aka frame pointer - varp uintptr // top of local variables - argp uintptr // pointer to function arguments - arglen uintptr // number of bytes at argp - argmap *bitvector // force use of this argmap + // fn is the function being run in this frame. If there is + // inlining, this is the outermost function. + fn funcInfo + + // pc is the program counter within fn. + // + // The meaning of this is subtle: + // + // - Typically, this frame performed a regular function call + // and this is the return PC (just after the CALL + // instruction). In this case, pc-1 reflects the CALL + // instruction itself and is the correct source of symbolic + // information. + // + // - If this frame "called" sigpanic, then pc is the + // instruction that panicked, and pc is the correct address + // to use for symbolic information. + // + // - If this is the innermost frame, then PC is where + // execution will continue, but it may not be the + // instruction following a CALL. This may be from + // cooperative preemption, in which case this is the + // instruction after the call to morestack. Or this may be + // from a signal or an un-started goroutine, in which case + // PC could be any instruction, including the first + // instruction in a function. Conventionally, we use pc-1 + // for symbolic information, unless pc == fn.entry(), in + // which case we use pc. + pc uintptr + + // continpc is the PC where execution will continue in fn, or + // 0 if execution will not continue in this frame. + // + // This is usually the same as pc, unless this frame "called" + // sigpanic, in which case it's either the address of + // deferreturn or 0 if this frame will never execute again. + // + // This is the PC to use to look up GC liveness for this frame. + continpc uintptr + + lr uintptr // program counter at caller aka link register + sp uintptr // stack pointer at pc + fp uintptr // stack pointer at caller aka frame pointer + varp uintptr // top of local variables + argp uintptr // pointer to function arguments + arglen uintptr // number of bytes at argp + argmap *bitvector // force use of this argmap } // ancestorInfo records details of where a goroutine was started.