# goffi - Development Roadmap

> **Strategic Approach**: Build production-ready Zero-CGO FFI with benchmarked performance
> **Philosophy**: Performance first, usability second, platform coverage third

**Last Updated**: 2026-07-21 | **Current Version**: v0.6.1 | **Strategy**: Benchmarks → Callbacks → ARM64 → Runtime → ABI → v1.0 LTS | **Milestone**: v0.6.1 (Android preview + fakecgo cleanup) → v0.7.0 RegisterFunc/Builder → v1.0.0 LTS

---

## 🎯 Vision

Build a **production-ready, zero-CGO FFI library for Go** with:
- **Performance**: < 200ns overhead (current: 88-114ns ✅)
- **Usability**: Simple, type-safe API
- **Coverage**: All major platforms and calling conventions
- **Quality**: 80%+ test coverage, comprehensive documentation

### Key Differentiators

✅ **Zero CGO Dependency**
- No C compiler required
- Easy cross-compilation
- Pure Go deployment

✅ **Performance First**
- Hand-optimized assembly for each ABI
- Benchmarked and validated
- < 5% overhead for GPU operations

✅ **Production Quality**
- 89.1% test coverage
- Typed error system
- Comprehensive documentation
- Active maintenance

---

## 🚀 Version Strategy

### Philosophy: Performance → Usability → Coverage → Stable

```
v0.1.0 (BENCHMARKS + QUALITY) ✅ RELEASED 2025-11-17
         ↓ (1 day - macOS completion)
v0.1.1 (macOS SUPPORT) ✅ RELEASED 2025-11-18
         ↓ (9 days - callback implementation)
v0.2.0 (CALLBACKS) ✅ RELEASED 2025-11-27
         ↓ (1 day - Windows hotfix)
v0.2.1 (WINDOWS HOTFIX) ✅ RELEASED 2025-11-27
         ↓ (ARM64 implementation)
v0.3.0-v0.3.7 (ARM64 SUPPORT) ✅ RELEASED 2025-12-29
         ↓ (CGO error handling)
v0.3.8 (CGO ERROR HANDLING) ✅ RELEASED 2026-01-24
         ↓ (callback fixes)
v0.3.9 (CALLBACK FIXES) ✅ RELEASED 2026-02-18
         ↓ (runtime integration)
v0.4.0 (CROSSCALL2 INTEGRATION) ✅ RELEASED 2026-02-27
         ↓ (usability)
v0.5.0 (PLATFORM COVERAGE) ✅ RELEASED 2026-03-29
         ↓ (struct ABI + CGO support)
v0.5.1 (STRUCT ABI + CGO_ENABLED=1) ✅ RELEASED 2026-05-13
         ↓ (variadic + vet fixes)
v0.5.2 (VARIADIC FUNCTIONS) ✅ RELEASED 2026-05-25
         ↓ (RegisterFunc + builder API)
v0.6.0 (REGISTERFUNC + BUILDER API) → 2026 Q3
         ↓ (advanced features)
v0.8.0 (ADVANCED FEATURES) → 2026 Q3-Q4
         ↓ (community adoption + validation)
v1.0.0 LTS → Long-term support release (2027 Q1)
```

### Critical Milestones

**v0.1.0** = Performance validated, production-ready for WebGPU ✅ RELEASED (2025-11-17)
- **88-114 ns/op** FFI overhead (BETTER than estimated 230ns!)
- 89.1% test coverage
- 5 typed errors
- Platform: Linux + Windows AMD64

**v0.1.1** = macOS support completion ✅ RELEASED (2025-11-18)
- **macOS AMD64** added to supported platforms
- System V ABI shared implementation (Linux + macOS)
- CI/CD coverage: 3 platforms (Linux, Windows, macOS)
- Coverage: **87.1%** (accurate calculation)

**v0.2.0** = Callback support for async APIs ✅ RELEASED (2025-11-27)
- **NewCallback API** for C-to-Go function calls
- 2000-entry trampoline table
- Thread-safe callback registry
- WebGPU async operations now supported
- Requested by: go-webgpu/webgpu project

**v0.2.1** = Windows callback hotfix ✅ RELEASED (2025-11-27)
- Windows ABI fix using `syscall.NewCallback`
- SEH exception limitation documented
- Platform-specific callback implementations

**v0.3.0-v0.3.7** = ARM64 support ✅ RELEASED (2025-12-29)
- **ARM64 architecture support** (Linux + macOS AAPCS64 ABI)
- Tested on Apple Silicon M3 Pro (64 ns/op)
- HFA returns, nested structs, mixed int/float support
- Contributed by: @ppoage (PR #9)

**v0.3.8** = CGO error handling ✅ RELEASED (2026-01-24)
- **Enterprise-grade CGO_ENABLED=1 error handling**
- Compile-time assertion: `GOFFI_REQUIRES_CGO_ENABLED_0`
- Clear documentation in README.md Requirements section
- Fixes confusing linker errors on Linux/macOS with gcc/clang

**v0.3.9** = Callback fixes ✅ RELEASED (2026-02-18)
- **ARM64 callback trampoline rewrite** (BL→MOVD+B)
- **Symbol rename** to avoid purego linker collision ([#15](https://github.com/go-webgpu/goffi/issues/15))
- Package-scoped assembly symbols (`·callbackTrampoline`/`·callbackDispatcher`)

**v0.4.0** = Runtime integration ✅ RELEASED (2026-02-27)
- **crosscall2 integration** for C-thread callbacks ([#16](https://github.com/go-webgpu/goffi/issues/16))
- Proper C→Go transition: `crosscall2 → runtime·load_g → runtime·cgocallback`
- Support callbacks from arbitrary C threads (Metal, wgpu-native internal threads)
- fakecgo trampoline register fixes

**v0.4.1** = ABI compliance hotfix ✅ RELEASED (2026-03-02)
- **Full ABI compliance audit** — 10 of 11 gaps fixed ([#19](https://github.com/go-webgpu/goffi/issues/19))
- AMD64/ARM64 stack spill for arguments beyond register count
- Float32 argument encoding fix (`math.Float32bits`)
- Struct return 9-16 bytes, sret hidden pointer, HFA stack spill
- Overflow detection, `runtime.KeepAlive` safety

**v0.5.0** = Platform coverage ✅ RELEASED (2026-03-29)
- **Windows ARM64** support (Snapdragon X Elite, tested by @SideFx)
- **FreeBSD amd64** support (cross-compile verified)
- 7 platform targets (Linux/Windows/macOS/FreeBSD × amd64 + Linux/macOS/Windows ARM64)

**v0.5.1** = Struct ABI + CGO_ENABLED=1 ✅ RELEASED (2026-05-13)
- **CGO_ENABLED=1 support** (PR #37 by @jiyeyuran) — dual-mode build, race detector compatible
- **Struct by-value argument passing** (PR #39, closes #33) — ≤8B/9-16B/>16B, INTEGER/SSE classification
- **Callback struct arguments** (PR #42 by @pekim, closes #41) — C→Go callbacks with struct args
- **9-16B struct return via XMM** (TASK-045) — 4 return modes: RAX:RDX, RAX:XMM0, XMM0:RAX, XMM0:XMM1
- **Race detector** — checkptr double-indirection fix (Go #58625), `-race` clean
- **E2E test infrastructure** — gcc-compiled C test library for struct passing verification
- Contributors: @jiyeyuran (CGO path maintainer), @pekim (callback structs)

**v0.5.2** = Variadic functions ✅ RELEASED (2026-05-25)
- **Variadic function support** — `PrepareVariadicCallInterface` with Apple ARM64 stack-force

**v0.5.3** = FreeBSD ARM64 ✅ RELEASED (2026-05-28)
- Build tag fix for FreeBSD ARM64 (8 platforms total)

**v0.5.4** = structs.HostLayout ✅ RELEASED (2026-06-15)
- ABI-safe struct layout for all assembly-interface structures

**v0.5.5** = Example fix + CI ✅ RELEASED (2026-06-15)
- Example avalue pointer bug fix, CI examples build verification

**v0.5.6** = Callback stack-move fix ✅ RELEASED (2026-07-05)
- Critical: `syscallArgs` moved to sync.Pool (goroutine stack-move safety)
- Discovered by @tie — `TestCallbackGrowStack` reproducer

**v0.6.0** = errno always-capture ✅ RELEASED (2026-07-12)
- **BREAKING**: `CallFunction` returns `(syscall.Errno, error)` — always captures C errno
- First pure-Go FFI with correct errno capture on Linux
- Assembly-level capture inside trampoline (thread-safe window)
- Platform support: `__errno_location` (Linux), `__error` (macOS/FreeBSD)

**v0.6.1** = Android ARM64 + fakecgo cleanup ✅ RELEASED (2026-07-21)
- **Android ARM64 Bionic** (guarded preview) — PR #62 by @besmpl
- fakecgo `purego_` → `goffi_` rename + dual copyright — PR #63
- LICENSE + NOTICE updated to GoGPU ecosystem pattern
- @besmpl added as CODEOWNER for Android paths

**v0.7.0** = RegisterFunc + Builder API (2026 Q3-Q4)
- RegisterFunc convenience API (ADR-008)
- Library struct + OpenLibraryBytes (ADR-009)
- NewFunc/Call/CallCtx ergonomic wrappers (ADR-009)

**v1.0.0** = Long-term support release (2027 Q1)
- API stability guarantee
- Security audit
- Published benchmarks vs CGO/purego
- 3+ years LTS support

---

## 📊 Current Status (v0.6.0)

**Phase**: errno always-capture, stack-move fix, 8 platforms. Planning v0.7.0 (RegisterFunc)

**What Works**:
- ✅ Dynamic library loading (`LoadLibrary`, `GetSymbol`, `FreeLibrary`)
- ✅ Function call interface (`PrepareCallInterface`)
- ✅ Function execution (`CallFunction`, `CallFunctionContext`)
- ✅ **Benchmarks**: 64-114 ns/op FFI overhead ✨
- ✅ **Typed errors**: 5 error types with `errors.As()` support
- ✅ **Context support**: Timeouts and cancellation
- ✅ **Cross-platform**: Linux + Windows + macOS (AMD64 + ARM64)
- ✅ **Type system**: Predefined descriptors for common types
- ✅ **Callbacks**: C-to-Go function calls (2000 entries)
- ✅ **89.6% test coverage** (exceeded 80% target)

**Performance**:
- ✅ AMD64: **88-114 ns/op** (Intel i7-1255U)
- ✅ ARM64: **64 ns/op** (Apple M3 Pro)
- ✅ **Verdict**: < 5% overhead for WebGPU operations (target achieved!)

**Platform Support**:
- ✅ Linux AMD64 (System V ABI)
- ✅ Windows AMD64 (Win64 ABI)
- ✅ macOS AMD64 (System V ABI)
- ✅ Linux ARM64 (AAPCS64 ABI)
- ✅ macOS ARM64 (AAPCS64 ABI) - Apple Silicon M1/M2/M3/M4

**Requirements**:
- ✅ `CGO_ENABLED=0` required (clear error message if CGO_ENABLED=1)
- ✅ Go 1.21+ recommended

**Documentation**:
- ✅ README.md with benchmarks and requirements
- ✅ docs/PERFORMANCE.md (comprehensive guide)
- ✅ CHANGELOG.md with migration guide
- ✅ CONTRIBUTING.md
- ✅ CODE_OF_CONDUCT.md
- ✅ SECURITY.md

---

## 📅 What's Next

### **v0.5.0 - Usability + Variadic** (Q2 2025)

**Goal**: Improve developer experience and add variadic function support

**Duration**: 2-3 months (Q2 2025)

**Features**:
1. **Builder Pattern API** (HIGH PRIORITY)
   ```go
   lib.Call("wgpuCreateInstance").
       Arg(nil).
       ReturnPointer(&instance)
   ```

2. **Variadic Function Support** (HIGH PRIORITY)
   - System V: AL register = SSE argument count
   - Win64: Float→GP register duplication
   - Examples: printf, sprintf, scanf

3. **Platform-Specific Struct Handling** (MEDIUM PRIORITY)
   - Windows `#pragma pack` support
   - MSVC vs GCC alignment differences

4. **Type-Safe Argument Helpers** (MEDIUM PRIORITY)
   ```go
   args := ffi.Args(ffi.Int32(42), ffi.String("hello"))
   ```

**Quality Targets**:
- Maintain 80%+ test coverage
- 0 linter issues
- API stability (no breaking changes)

---

### **v0.8.0 - Advanced Features** (Q4 2025)

**Goal**: Advanced FFI capabilities and tooling

**Duration**: 2-3 months (Q4 2025)

**Advanced Features**:
1. **Codegen Tool (`goffi-gen`)** (HIGH PRIORITY)
   ```bash
   goffi-gen --input=wgpu.h --output=wgpu.go
   ```
   - C header parser
   - Go binding generator
   - JSON intermediate format
   - Type mapping customization

2. **Struct Builder API** (MEDIUM PRIORITY)
   ```go
   structType := ffi.Struct().
       Field("x", types.Float32).
       Field("y", types.Float32).
       Build()
   ```

3. **Performance Optimizations** (MEDIUM PRIORITY)
   - JIT stub generation (reduce indirect jumps)
   - Batch API (`CallBatch()` for multiple calls)
   - Assembly micro-optimizations (target: 70ns)

4. **Thread-Local Storage (TLS)** (LOW PRIORITY)
   - Per-thread state management
   - OpenGL context binding support
   - Thread-safe library handles

**Quality Targets**:
- Codegen tool with 90%+ C header coverage
- Tooling documentation
- Advanced examples (OpenGL, Vulkan)

---

### **v1.0.0 - Long-Term Support Release** (Q1 2026)

**Goal**: Production-ready LTS release with stability guarantees

**Requirements**:
- v0.8.x stable for 3+ months
- Positive community feedback
- No critical bugs
- API proven in production (WebGPU, Vulkan, etc.)

**LTS Guarantees**:
- ✅ **API stability** (no breaking changes in v1.x.x)
- ✅ **Long-term support** (3+ years)
- ✅ **Semantic versioning** strictly followed
- ✅ **Security updates** and bug fixes
- ✅ **Performance improvements** (non-breaking)
- ✅ **Documentation** maintained and updated

**Deliverables**:
1. **Security Audit** by external experts
2. **Benchmark Suite** vs CGO/purego (published)
3. **Reference Implementations**:
   - WebGPU bindings (wgpu-native)
   - Vulkan bindings
   - SQLite bindings
4. **Comprehensive Documentation**:
   - Book-style guide
   - API reference (pkg.go.dev)
   - Video tutorials
5. **Support Policy**:
   - GitHub Discussions for Q&A
   - Issue triage within 48h
   - Critical fixes within 1 week

---

## 📚 Resources

**Official Documentation**:
- README.md - Project overview
- docs/PERFORMANCE.md - Performance guide
- CHANGELOG.md - Version history
- CONTRIBUTING.md - Development guide
- SECURITY.md - Security policy

**Development**:
- API_TODO.md - Detailed task backlog
- .github/workflows/ci.yml - CI/CD pipeline
- scripts/pre-release-check.sh - Quality checks

**Reference**:
- libffi: https://github.com/libffi/libffi
- purego: https://github.com/ebitengine/purego
- wgpu-native: https://github.com/gfx-rs/wgpu-native

---

## 📊 Quality Metrics

**Current (v0.4.0)**:
- ✅ Test coverage: 89.6% (target: 80%+)
- ✅ Linter issues: 0
- ✅ Benchmarks: 64-114 ns/op (AMD64 + ARM64)
- ✅ Platforms: 5 (Linux, Windows, macOS × AMD64/ARM64)
- ✅ CGO requirement: Clear error message

**Target (v1.0.0)**:
- 🎯 Test coverage: 90%+
- 🎯 Linter issues: 0
- 🎯 Benchmarks: < 100ns average
- 🎯 Platforms: 5+ (Linux, Windows, macOS × AMD64/ARM64)
- 🎯 Documentation: Comprehensive (book-style)
- 🎯 Community: Active (10+ contributors)

---

## 🔬 Development Philosophy

**Performance First**:
- Every change benchmarked
- Assembly optimized per platform
- Zero allocations in hot paths
- Profiling before optimization

**Quality Over Speed**:
- Comprehensive tests (unit + integration + benchmarks)
- Linting with 34+ security-focused linters
- Documentation updated with code
- Security-first design

**Community Driven**:
- Public roadmap (this file)
- Open issue discussion
- RFC process for major changes
- Contributor recognition

---

## 📞 Support & Feedback

**Questions**:
- GitHub Discussions: https://github.com/go-webgpu/goffi/discussions
- GitHub Issues: https://github.com/go-webgpu/goffi/issues

**Contributing**:
- See CONTRIBUTING.md
- Check API_TODO.md for open tasks
- Join discussions on roadmap priorities

**Security**:
- See SECURITY.md
- Private disclosure: https://github.com/go-webgpu/goffi/security/advisories/new

---

*Version 1.4 (Updated 2026-02-27)*
*Current: v0.4.0 (crosscall2 integration) | Next: v0.5.0 (Usability) | Target: v1.0.0 LTS*