bininspect

type FieldIdentifier struct {
	// Fully-qualified name of the struct
	StructName string
	// Name of the field in the struct
	FieldName string
}

type FunctionConfiguration struct {
	IncludeReturnLocations bool
	ParamLookupFunction    ParameterLookupFunction
}

type FunctionMetadata struct {
	// The virtual address for the function's entrypoint for non-PIE's,
	// or offset to the file load address for PIE's.
	//
	// This should really probably be the location of the end of the prologue
	// (which might help with parameter locations being half-spilled),
	// but so far using the first PC position in the function has worked
	// for the functions we're tracing.
	// See:
	// - https://github.com/go-delve/delve/pull/2704#issuecomment-944374511
	//   (which implies that the instructions in the prologue
	//   might get executed multiple times over the course of a single function call,
	//   though I'm not sure under what circumstances this might be true)
	EntryLocation uint64
	// A list of parameter metadata structs
	// used for extracting the function arguments in the eBPF probe.
	//
	// When optimizations are enabled, and depending on the Go version,
	// it has been observed that these parameter locations are sometimes missing pieces
	// (either due to them being eliminated on purpose
	// (as in the case of an unused slice length/capacity/data) being omitted)
	// or due to (spooky behavior in the compiler?))
	// or missing entire parameters (again due to (spooky behavior in the compiler?)).
	// This is unfortunate; I don't think there is a clean way to work around this
	// (since the data is just missing).
	// The best solution I have found is to:
	// - manually handle cases where entire parameters are missing
	//   if it's known that they only occur on a specific Go version
	//   (Go 1.16.* is one that I have found to be troublesome)
	//   and insert the appropriate parameter locations if known.
	// - if all of the parameters are missing,
	//   then I have found that manually re-implementing
	//   the stack/register allocation algorithm for function arguments/returns
	//   (depending on the ABI, and using the sizes of the values from the type metadata)
	//   can work to still obtain the parameters at runtime.
	//   This is probably much more brittle
	//   than getting the locations directly from the debug information.
	//
	// If the outer result's IncludesDebugSymbols is false,
	// then this slice always will be nil/empty.
	Parameters []ParameterMetadata
	// A list of locations for each return instruction in the compiled function machine code.
	// Each element is the virtual address for the function's entrypoint for non-PIE's,
	// or offset to the file load address for PIE's.
	// Only given if `IncludesReturn` is true.
	//
	// Note that this may not behave well with panics or defer statements.
	ReturnLocations []uint64
}

type GoABI string

type GoArch string

type GoroutineIDMetadata struct {
	// The offset of the `goid` field within `runtime.g`
	GoroutineIDOffset uint64
	// Whether the pointer to the current `runtime.g` value is in a register.
	// If true, then `RuntimeGRegister` is given.
	// Otherwise, `RuntimeGTLSAddrOffset` is given
	RuntimeGInRegister bool

	// The register that the pointer to the current `runtime.g` is in.
	RuntimeGRegister int
	// The offset of the `runtime.g` value within thread-local-storage.
	RuntimeGTLSAddrOffset uint64
}

type ParameterLookupFunction func(delve.GoVersion, string) ([]ParameterMetadata, error)

type ParameterMetadata struct {
	// Total size in bytes.
	TotalSize int64
	// Kind of variable.
	Kind reflect.Kind

	// Pieces that make up the location of this parameter at runtime
	Pieces []ParameterPiece
}

type ParameterPiece struct {
	// Size of this piece in bytes
	Size int64
	// True if this piece is contained in a register.
	InReg bool
	// Offset from the stackpointer.
	// Only given if the piece resides on the stack.
	StackOffset int64
	// Register number of the piece.
	// Only given if the piece resides in registers.
	Register int
}

type Result struct {
	Arch                GoArch
	ABI                 GoABI
	GoVersion           goversion.GoVersion
	Functions           map[string]FunctionMetadata
	StructOffsets       map[FieldIdentifier]uint64
	GoroutineIDMetadata GoroutineIDMetadata
}

type StructLookupFunction func(delve.GoVersion, string) (uint64, error)