abi

Documentation

Overview

Package abi provides an interface to the platform-standard ABI calling conventions and type system (typically C).

Helpful links: https://go.googlesource.com/go/+/refs/heads/master/src/cmd/compile/abi-internal.md https://dyncall.org/docs/manual/manualse11.html https://github.com/ziglang/zig/blob/master/src/arch

Index

• Variables
• type CallingConvention
  • func CGO(fn Function) (cc CallingConvention, err error)
  • func Internal(fn Function) (cc CallingConvention, err error)
  • func Zero(fn Function) (cc CallingConvention, err error)
• type File
• type FilePosition
• type Function
  • func FunctionOf(rtype reflect.Type) Function
• type HardwareLocation
• type IndirectLocation
• type JumpBuffer
• type Location
  • func (loc Location) Equals(rhs Location) bool
  • func (val Location) Read() []cpu.Instruction
  • func (val Location) Send() []cpu.Instruction
• type Operation
  • func (op Operation) IsCopy() bool
  • func (op Operation) IsMove() bool
  • func (op Operation) String() string
• type Pointer
• type String
• type Type
• type Uintptr
• type Value
  • func ValueOf(rtype reflect.Type) Value
  • func (val Value) Align() uintptr
  • func (val Value) Pin(location Location) []cpu.Location
  • func (val Value) Size() uintptr

Variables

var HardwareLocations = xyz.AccessorFor(HardwareLocation.Values)

var Locations = xyz.AccessorFor(Location.Values)

var Values = xyz.AccessorFor(Value.Values)

Types

type CallingConvention

type CallingConvention struct {
	Call cpu.Instruction
	Args []Location
	Rets []Location
}

CallingConvention describes the calling convention argument and return value locations for a function.

func CGO

func CGO(fn Function) (cc CallingConvention, err error)

CGO implementation is used to call the function. ie. with dyncall.

func Internal

func Internal(fn Function) (cc CallingConvention, err error)

Internal Go ABI calling convention (requirement for direct cpu register access) any arguments that fit entirely into the remaining registers are passed in registers. The rest are passed on the stack, as per ABI0. https://go.googlesource.com/go/+/refs/heads/master/src/cmd/compile/abi-internal.md

func Zero

func Zero(fn Function) (cc CallingConvention, err error)

Zero is the Go ABI0 calling convention. All arguments are passed on the stack in right to left order.

type File

type File Uintptr[File]

type FilePosition

type FilePosition Uintptr[FilePosition]

type Function

type Function struct {
	Vars bool // varargs/variadic
	Args []Value
	Rets []Value
}

Function describes the low-level fixed-size values for a function.

func FunctionOf

func FunctionOf(rtype reflect.Type) Function

FunctionOf returns the Function of the given reflect function type.

type HardwareLocation

type HardwareLocation xyz.Tagged[[8]byte, struct {
	Register xyz.Case[HardwareLocation, cpu.Location] // standard register.
	Floating xyz.Case[HardwareLocation, cpu.Location] // standard floating-point register.
	Software xyz.Case[HardwareLocation, cpu.SlowFunc] // platform-native ABI push/pop.
	Specific xyz.Case[HardwareLocation, cpu.ArchFunc] // architecture-specific hardware location.
	StackRtl xyz.Case[HardwareLocation, uintptr]      // offset to the parameter on a right to left stack.
	StackLtr xyz.Case[HardwareLocation, uintptr]      // offset to the parameter on a left to right stack.
}]

HardwareLocation describes the physical and direct location of a value.

type IndirectLocation

type IndirectLocation struct {
	Location Location // hardware location of the pointer.
	Relative uintptr  // relative offset to the pointer.
}

IndirectLocation describes a value passed by reference.

type JumpBuffer

type JumpBuffer Uintptr[JumpBuffer]

type Location

type Location xyz.Tagged[any, struct {
	Returned Location                             // value is returned by the call.
	Software xyz.Case[Location, cpu.SlowFunc]     // software location.
	Hardware xyz.Case[Location, HardwareLocation] //physical location.
	Multiple xyz.Case[Location, []Location]       // multiple values passed by value.
	Indirect xyz.Case[Location, IndirectLocation] // value passed by reference.
}]

Location of a function's argument or return value.

func (Location) Equals

func (loc Location) Equals(rhs Location) bool

func (Location) Read

func (val Location) Read() []cpu.Instruction

func (Location) Send

func (val Location) Send() []cpu.Instruction

type Operation

type Operation byte

CallOperation used to transform arguments from Go to the platform-native calling convention. The instructions operate on a 64-instruction virtual machine with the following five registers:

• $normal 64bit register: the register used for most operations.
• $length 64bit register: the register used to store length.
• $assert 64bit register: the register used to make assertions.
• $result 64bit register: the register set by assertions.

The following counters are also available:

• program counter (PC): the current instruction.
• caller counter: the Nth current caller value.
• callee counter: the Nth current callee value.
• loop counter: the Nth current loop iteration.

If the $result register is set to a non-zero value before the function is called, the function panics.

const (
	Operations Operation = 64 - iota // no operation, used for padding.

	// special instructions.
	JumpToCall // calls the calling context's function, second time calls the error function, third panics. swaps meaning of SendArg* and RecvArg*. functions.

	// data
	LookupType // load the type of the current argument into the $assert register.
	LookupData // load the constant associated with the current argument into the $assert register.

	// general purpose.
	NormalSet0 // sets the $normal register to 0.
	NormalSet1 // sets the $normal register to 1.
	SwapLength // swap the $normal and $length registers.
	SwapAssert // swap the $normal and $assert registers.

	// Move Go values to registers, before [NormalCall] these refer
	// to the caller's arguments, after [NormalCall] they refer to
	// the return values to pass back to the caller.
	MoveValByt // move 8bit into $normal
	MoveValU16 // move 16bit into $normal
	MoveValU32 // move 32bit into $normal
	MoveValU64 // move 64bit into $normal
	MoveValF32 // move float32 into $normal
	MoveValF64 // move float64 into $normal
	MoveValPtr // move uintptr into $normal
	MoveValStr // move string into $normal + $length
	MoveValMap // move map into $normal + $length
	MoveValArr // move slice into $normal + $length, capacity is ignored.
	MoveValAny // move interface into $normal + $length (type)
	MoveValTim // move time.Time into $normal + $length, timezone is ignored.
	MoveValErr // move error into $normal as integer, or $assert into results.
	MoveNewVal // reset the caller's value counter back to zero.

	CopyValByt // copy $normal as byte
	CopyValU16 // copy $normal as uint16
	CopyValU32 // copy $normal as uint32
	CopyValU64 // copy $normal as uint64
	CopyValF32 // copy $normal as float32
	CopyValF64 // copy $normal as float64
	CopyValPtr // copy $normal as uintptr
	CopyValStr // copy $normal + $length as null-terminated string
	CopyValArr // copy $normal + $length as array pointer.
	CopyValLen // copy $length as uintptr
	CopyValVar // copy $normal + $length as varargs
	CopyNewVal // reset the callee's value counter back to zero.

	MoveStruct // subsequent move operations are apply to struct members.
	CopyStruct // subsequent copy operations are aggreated as a struct.
	DoneStruct // terminates [MoveStruct] and [CopyStruct] ands returns move and copy to normal.

	// iterators
	ForEachMap // push PC and repeat $normal, moves relate to the current map key and value, as if they were a struct.
	ForEachLen // push the program counter onto the stack and repeats the next instructions in [ForEachEnd] $length times.
	ForEachIdx // writes the current loop counter into the $normal register.
	ForEachEnd // pop the $length register from the stack and returns to normal execution.

	// push the $normal register onto the stack and then dereferences it as $normal
	// if the $normal register is zero, the stack is not pushed and execution is
	// advanced to the next matching [DoneOffset] instruction. cylical references
	// are resolved. subsequent SendArg* instructions will add perform the copy
	PushOffset
	PushPtrPtr // like [PushOffset] but for [Pointer] types.
	DoneOffset // pop the $normal register from the stack. Move ahead ptrsize bytes.

	// strings
	SizeString // set $length to the length of the null-terminated [String] pointed to by $normal.
	NullString // asserts that the $normal + $length string has a null terminator, copying it as neccasary.

	// allocation.
	MakeLength // subsequent copy instructions will add their sizes to the $assert register.
	DoneLength // pointer to empty memory of size $assert is written into the $length register, move and copy return to default behaviour.
	MakeMemory // subsequent copy instructions will write to dynamic heap memory.
	DoneMemory // pointer to heap memory from [MakeMemory] into the $normal register, , move and copy return to default behaviour.

	// garbage collection.
	FreeMemory // release ownership of the current argument.
	KeepMemory // maintain ownership of the current argument (keepalive)..

	// pointer instructions.
	MakePtrPtr // make the pointer inside the $normal register, a [Pointer] (or [Uintptr]).
	LoadPtrPtr // load the pointer inside the $normal register, a [Pointer] (or [Uintptr]) into $normal.

	// printf support.
	MakeFormat // load $normal + $length as a C string into the assert register.
	NewClosure // convert the $normal register into an ABI-compatible function pointer of type $assert.

	// time instructions.
	NanoTiming // swap the $normal nano time with the $format register.
	UnixTiming // swap the $normal unix milli with into the $format register.

	// assertions.
	AssertFlip // flips inverts the $failed register between 1 and 0.
	AssertLess // write sets the $failed register if the $normal register is not less than the $assert register.
	AssertSame // write sets the $failed register if the $normal register is not equal to the $assert register.
	AssertMore // write sets the $failed register if the $normal register is not greater than the $assert register.

	// write 1 into the $assert register if the $normal + $length register does
	// not have enough capacity to store the result of the C printf format string
	// specified by the $format register. Also checks if the types are correct.
	AssertArgs
)

func (Operation) IsCopy

func (op Operation) IsCopy() bool

func (Operation) IsMove

func (op Operation) IsMove() bool

func (Operation) String

func (op Operation) String() string

String implements fmt.Stringer and returns the name of the instruction.

type Pointer

type Pointer[T any] struct {
	// contains filtered or unexported fields
}

Pointer to a known fixed-size value.

type String

type String struct {
	// contains filtered or unexported fields
}

String is a null-terminated string value.

type Type

type Type func(Function) (CallingConvention, error)

Type returns the calling convention locations for the given argument and return types.

type Uintptr

type Uintptr[T any] struct {
	// contains filtered or unexported fields
}

Uintptr is an opaque pointer-like value that refers to a foreign object. May or may not be an actual pointer.

type Value

type Value xyz.Tagged[any, struct {
	Bytes0 Value
	Bytes1 Value
	Bytes2 Value
	Bytes4 Value
	Bytes8 Value
	Float4 Value
	Float8 Value
	Memory Value // pointer
	Sizing Value
	Struct xyz.Case[Value, []Value]
}]

Value represents the fixed-sized value type.

func ValueOf

func ValueOf(rtype reflect.Type) Value

func (Value) Align

func (val Value) Align() uintptr

func (Value) Pin

func (val Value) Pin(location Location) []cpu.Location

func (Value) Size

func (val Value) Size() uintptr