goffi

goffi — Zero-CGO FFI for Go

Pure Go Foreign Function Interface for calling C libraries without CGO. Designed for WebGPU and GPU computing — zero C dependencies, zero per-call allocations, 88–114 ns overhead.

Deep dive: How We Call C Libraries Without a C Compiler — architecture, assembly, callbacks, and ecosystem.

// Load library, prepare once, call many times — no CGO required
handle, _ := ffi.LoadLibrary("wgpu_native.dll")
sym, _ := ffi.GetSymbol(handle, "wgpuCreateInstance")

cif := &types.CallInterface{}
ffi.PrepareCallInterface(cif, types.DefaultCall, returnType, argTypes)
ffi.CallFunction(cif, sym, unsafe.Pointer(&result), args)

Features

Quick Start

Installation

go get github.com/go-webgpu/goffi

Requirements

goffi requires CGO_ENABLED=0. This is automatic when no C compiler is installed or when cross-compiling. If you have gcc/clang:

CGO_ENABLED=0 go build ./...

Why? goffi uses Go's cgo_import_dynamic for dynamic library loading, which only activates when CGO is disabled.

Example: Calling strlen

package main

import (
	"fmt"
	"runtime"
	"unsafe"

	"github.com/go-webgpu/goffi/ffi"
	"github.com/go-webgpu/goffi/types"
)

func main() {
	// Load platform-specific C library
	libName := "libc.so.6"
	if runtime.GOOS == "windows" {
		libName = "msvcrt.dll"
	}

	handle, err := ffi.LoadLibrary(libName)
	if err != nil {
		panic(err)
	}
	defer ffi.FreeLibrary(handle)

	strlen, err := ffi.GetSymbol(handle, "strlen")
	if err != nil {
		panic(err)
	}

	// Prepare call interface once — reuse for all subsequent calls
	cif := &types.CallInterface{}
	err = ffi.PrepareCallInterface(
		cif,
		types.DefaultCall,                                     // auto-detects platform ABI
		types.UInt64TypeDescriptor,                            // return: size_t
		[]*types.TypeDescriptor{types.PointerTypeDescriptor},  // arg: const char*
	)
	if err != nil {
		panic(err)
	}

	// Call strlen — avalue elements are pointers TO argument values
	testStr := "Hello, goffi!\x00"
	strPtr := uintptr(unsafe.Pointer(unsafe.StringData(testStr)))
	var length uint64

	err = ffi.CallFunction(cif, strlen, unsafe.Pointer(&length), []unsafe.Pointer{unsafe.Pointer(&strPtr)})
	if err != nil {
		panic(err)
	}

	fmt.Printf("strlen(%q) = %d\n", testStr[:len(testStr)-1], length)
	// Output: strlen("Hello, goffi!") = 13
}

Performance

FFI overhead: 88–114 ns/op (Windows AMD64, Intel i7-1255U)

At 60 FPS with ~50 FFI calls per frame, overhead is 5 µs per frame — 0.03% of the 16.6 ms budget. Unmeasurable in profiling.

See docs/PERFORMANCE.md for detailed analysis, optimization strategies, and when NOT to use goffi.

Architecture

goffi transitions from Go's managed runtime to C code through three layers:

Go Code
  │  ffi.CallFunction()
  ▼
runtime.cgocall               ← Go runtime: system stack switch, GC coordination
  │
  ▼
Assembly Wrapper              ← Hand-written: load GP/SSE registers per ABI
  │  CALL target_function
  ▼
C Function                    ← External library

Three ABIs, hand-written assembly for each:

See docs/ARCHITECTURE.md for the full technical deep dive.

Callbacks (C → Go)

WebGPU fires async callbacks from internal Metal/Vulkan threads. These threads have no goroutine — calling Go directly would crash.

goffi uses crosscall2 for safe C→Go transitions from any thread:

cb := ffi.NewCallback(func(status uint32, adapter uintptr, msg uintptr, ud uintptr) {
    // Safe even when called from a C thread
    result.handle = adapter
    close(done)
})

ffi.CallFunction(cif, wgpuRequestAdapter, nil, args)
<-done // Wait for GPU driver callback

2000 pre-compiled trampoline entries per process. AMD64: 5 bytes/entry. ARM64: 8 bytes/entry.

Error Handling

Five typed error types for precise diagnostics:

handle, err := ffi.LoadLibrary("nonexistent.dll")
if err != nil {
	var libErr *ffi.LibraryError
	if errors.As(err, &libErr) {
		fmt.Printf("Failed to %s %q: %v\n", libErr.Operation, libErr.Name, libErr.Err)
	}
}

Comparison: goffi vs purego vs CGO

Choose goffi for GPU/real-time workloads: struct passing, zero per-call overhead, callback float returns, typed errors.

Choose purego for general-purpose bindings: string auto-marshaling, broad architecture support, less boilerplate.

See also: JupiterRider/ffi — pure Go binding for libffi via purego. Supports struct pass/return and variadic functions; requires libffi at runtime.

Known Limitations

Windows: C++ exceptions may crash the program (#12516)

• Go runtime limitation, not goffi-specific. Go 1.22+ added partial SEH support (#58542), but edge cases remain.
• Workaround: build native libraries with panic=abort.

Windows: float return values not captured from XMM0

• syscall.SyscallN returns RAX only. Go syscall package limitation.

Variadic functions not supported (printf, sprintf)

• Use non-variadic wrappers. Planned for v0.5.0.

Struct packing follows System V ABI only

• Windows #pragma pack not honored. Manually specify Size/Alignment in TypeDescriptor.

No bitfields in struct types.

Unix: duplicate symbol conflict with purego (#22)

• When using goffi and purego in the same binary with CGO_ENABLED=0, the linker reports duplicated definition of symbol _cgo_init. Both libraries include internal/fakecgo which defines identical runtime symbols.
• Workaround: build with -tags nofakecgo to disable goffi's fakecgo, relying on purego's copy:

  CGO_ENABLED=0 go build -tags nofakecgo ./...
  

Platform Support

Roadmap

See CHANGELOG.md for version history and ROADMAP.md for the full plan.

Testing

go test ./...                          # all tests
go test -cover ./...                   # with coverage (89%)
go test -bench=. -benchmem ./ffi       # benchmarks
go test -v ./ffi                       # verbose, auto-detects platform

Documentation

Contributing

See CONTRIBUTING.md for guidelines.

1. Fork → feature branch → tests (80%+ coverage) → lint → PR
2. Conventional commits: feat:, fix:, docs:, test:

Acknowledgments

• purego — proved that pure Go FFI is possible. The crosscall2 callback mechanism, fakecgo approach, and assembly trampoline patterns were pioneered by purego. goffi exists because purego cleared the path.
• libffi — reference for FFI architecture patterns and CIF design.
• Go runtime — runtime.cgocall for GC-safe stack switching, crosscall2 for C→Go transitions.

Ecosystem

goffi powers an ecosystem of pure Go GPU libraries:

License

MIT — see LICENSE.

goffi v0.4.1 | GitHub | pkg.go.dev | Dev.to