ane

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 11, 2026 License: MIT Imports: 3 Imported by: 1

Documentation

Overview

Package ane provides high-level access to the Apple Neural Engine.

Open a Runtime, compile MIL programs into Kernels, and evaluate them on the ANE hardware. IOSurface buffers are managed automatically. 

rt, err := ane.Open()
if err != nil {
	log.Fatal(err)
}
defer rt.Close()

k, err := rt.Compile(ane.CompileOptions{
	MILText:    milText,
	WeightBlob: blob,
	ModelType:  ane.ModelTypeMIL,
})
if err != nil {
	log.Fatal(err)
}
defer k.Close()

k.WriteInputF32(0, input)
if err := k.Eval(); err != nil {
	log.Fatal(err)
}
k.ReadOutputF32(0, output)

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrNoANE                    = errors.New("ane: no ANE hardware available")
	ErrCompileBudgetExhausted   = errors.New("ane: compile budget exhausted")
	ErrMapFailed                = errors.New("ane: IOSurface mapping failed")
	ErrUnsupportedSelector      = errors.New("ane: unsupported selector")
	ErrVirtualClientUnavailable = errors.New("ane: virtual client unavailable")
	ErrModelLoad                = errors.New("ane: model load failed")
	ErrEval                     = errors.New("ane: evaluation failed")
	ErrUnsupportedLayout        = errors.New("ane: unsupported tensor layout")
)

Functions

func FP16ToFloat32 

func FP16ToFloat32(h uint16) float32

FP16ToFloat32 converts an IEEE 754 half-precision value to float32.

func Float32ToFP16 

func Float32ToFP16(f float32) uint16

Float32ToFP16 converts a float32 to IEEE 754 half-precision.

func RowStrideFor 

func RowStrideFor(width, elemSize int) int

RowStrideFor computes the minimum 64-byte-aligned row stride.

Types

type ANEError 

type ANEError struct {
	Op    string // operation that failed
	Class string // error domain or class
	Code  int    // error code
	Err   error  // underlying error
}

ANEError wraps an error from the ANE subsystem with context.

func (*ANEError) Error 

func (e *ANEError) Error() string

func (*ANEError) Is 

func (e *ANEError) Is(target error) bool

func (*ANEError) Unwrap 

func (e *ANEError) Unwrap() error

type CompileOptions 

type CompileOptions struct {
	ModelType ModelType

	// For ModelTypeMIL:
	MILText []byte // MIL program text
	// Legacy single-weight MIL fields.
	WeightBlob []byte // weight binary blob (may be nil)
	WeightPath string // model path key for weight dict (default: "@model_path/weights/weight.bin")
	// WeightFiles allows MIL graphs with multiple named BLOBFILE inputs.
	// If both WeightBlob and WeightFiles are set, they are merged.
	WeightFiles []WeightFile

	// For ModelTypePackage:
	PackagePath string // path to .mlmodelc directory
	ModelKey    string // key for model dictionary (default: "s")

	QoS           uint32 // quality-of-service class (0 = default 21)
	PerfStatsMask uint32 // perf stats bitmask (0 = disabled)
}

CompileOptions configures model compilation.

type DeviceInfo 

type DeviceInfo struct {
	HasANE       bool
	NumCores     uint32
	Architecture string
	Product      string
	BuildVersion string
	IsVM         bool
}

DeviceInfo describes the ANE hardware present on the system.

func Probe 

func Probe() (DeviceInfo, error)

Probe returns device information about the ANE. On non-Darwin platforms, it always reports no ANE.

type Diagnostics 

type Diagnostics struct {
	ModelQueueDepth      int
	ModelQueueDepthKnown bool
	ProgramClass         string
	ProgramClassKnown    bool
}

Diagnostics contains best-effort runtime diagnostic information about a kernel.

type EvalStats 

type EvalStats struct {
	HWExecutionNS uint64 // hardware execution time in nanoseconds
}

EvalStats contains hardware performance statistics from an evaluation.

type Kernel 

type Kernel struct{}

Kernel represents a compiled and loaded model ready for evaluation.

func (*Kernel) Close 

func (k *Kernel) Close() error

func (*Kernel) Diagnostics 

func (k *Kernel) Diagnostics() Diagnostics

func (*Kernel) Eval 

func (k *Kernel) Eval() error

func (*Kernel) EvalAsync 

func (k *Kernel) EvalAsync() <-chan error

func (*Kernel) EvalAsyncWithCallback 

func (k *Kernel) EvalAsyncWithCallback(fn func(error))

func (*Kernel) EvalBidirectional 

func (k *Kernel) EvalBidirectional(waitPort uint32, waitValue uint64, signalPort uint32, signalValue uint64, cfg SharedEventEvalOptions) error

func (*Kernel) EvalWithSignalEvent 

func (k *Kernel) EvalWithSignalEvent(signalPort uint32, signalValue uint64, cfg SharedEventEvalOptions) error

func (*Kernel) EvalWithStats 

func (k *Kernel) EvalWithStats() (EvalStats, error)

func (*Kernel) InputAllocSize 

func (k *Kernel) InputAllocSize(i int) int

func (*Kernel) InputChannels 

func (k *Kernel) InputChannels(i int) int

func (*Kernel) InputLayout 

func (k *Kernel) InputLayout(i int) TensorLayout

func (*Kernel) InputSurface 

func (k *Kernel) InputSurface(i int) uintptr

func (*Kernel) InputSurfaces 

func (k *Kernel) InputSurfaces() []uintptr

func (*Kernel) MetalInputBuffer 

func (k *Kernel) MetalInputBuffer(d *MetalDevice, i int) (any, error)

func (*Kernel) MetalOutputBuffer 

func (k *Kernel) MetalOutputBuffer(d *MetalDevice, i int) (any, error)

func (*Kernel) NumInputs 

func (k *Kernel) NumInputs() int

func (*Kernel) NumOutputs 

func (k *Kernel) NumOutputs() int

func (*Kernel) OutputAllocSize 

func (k *Kernel) OutputAllocSize(i int) int

func (*Kernel) OutputChannels 

func (k *Kernel) OutputChannels(i int) int

func (*Kernel) OutputLayout 

func (k *Kernel) OutputLayout(i int) TensorLayout

func (*Kernel) OutputSurface 

func (k *Kernel) OutputSurface(i int) uintptr

func (*Kernel) OutputSurfaces 

func (k *Kernel) OutputSurfaces() []uintptr

func (*Kernel) ReadOutput 

func (k *Kernel) ReadOutput(i int, data []byte) error

func (*Kernel) ReadOutputF32 

func (k *Kernel) ReadOutputF32(i int, data []float32) error

func (*Kernel) ReadOutputFP16 

func (k *Kernel) ReadOutputFP16(i int, data []float32) error

func (*Kernel) ReadOutputFP16Channels 

func (k *Kernel) ReadOutputFP16Channels(i, channel int, data []float32) error

func (*Kernel) Spatial 

func (k *Kernel) Spatial(i int) int

func (*Kernel) WriteInput 

func (k *Kernel) WriteInput(i int, data []byte) error

func (*Kernel) WriteInputF32 

func (k *Kernel) WriteInputF32(i int, data []float32) error

func (*Kernel) WriteInputFP16 

func (k *Kernel) WriteInputFP16(i int, data []float32) error

func (*Kernel) WriteInputFP16Channels 

func (k *Kernel) WriteInputFP16Channels(i, channel int, data []float32) error

type MetalDevice 

type MetalDevice struct{}

MetalDevice wraps a Metal GPU device for zero-copy interop with ANE.

func OpenMetal 

func OpenMetal() (*MetalDevice, error)

func (*MetalDevice) Close 

func (d *MetalDevice) Close() error

func (*MetalDevice) MetalSharedEvent 

func (d *MetalDevice) MetalSharedEvent(ev *SharedEvent) (any, error)

func (*MetalDevice) NewMetalSharedEvent 

func (d *MetalDevice) NewMetalSharedEvent() (any, *SharedEvent, error)

type ModelType 

type ModelType int

ModelType selects the compilation path. 

const (
	ModelTypeMIL     ModelType = iota // In-memory MIL text + weights
	ModelTypePackage                  // On-disk .mlmodelc package
)

type Pipeline 

type Pipeline struct{}

Pipeline manages SharedEvent synchronization between ANE and Metal.

func NewPipeline 

func NewPipeline(_ *MetalDevice) (*Pipeline, error)

func (*Pipeline) ANEEvent 

func (p *Pipeline) ANEEvent() *SharedEvent

func (*Pipeline) ANEToMetal 

func (p *Pipeline) ANEToMetal(_ *Kernel) error

func (*Pipeline) Bidirectional 

func (p *Pipeline) Bidirectional(_ *Kernel) error

func (*Pipeline) Close 

func (p *Pipeline) Close() error

func (*Pipeline) Counter 

func (p *Pipeline) Counter() uint64

func (*Pipeline) Metal 

func (p *Pipeline) Metal() *MetalDevice

func (*Pipeline) MetalEvent 

func (p *Pipeline) MetalEvent() any

func (*Pipeline) WaitOnANE 

func (p *Pipeline) WaitOnANE(_ *Kernel) error

type PooledRequest 

type PooledRequest struct{}

PooledRequest is a request checked out from a pool.

func (*PooledRequest) Eval 

func (pr *PooledRequest) Eval() error

func (*PooledRequest) Release 

func (pr *PooledRequest) Release()

type RequestPool 

type RequestPool struct{}

RequestPool pre-allocates a ring of ANE requests for pipelined evaluation.

func NewRequestPool 

func NewRequestPool(k *Kernel, depth int) (*RequestPool, error)

func (*RequestPool) Acquire 

func (p *RequestPool) Acquire() *PooledRequest

func (*RequestPool) Close 

func (p *RequestPool) Close() error

type Runtime 

type Runtime struct{}

Runtime manages a connection to the ANE hardware.

func Open 

func Open() (*Runtime, error)

Open creates a new Runtime for ANE inference. On non-Darwin platforms, it always returns ErrNoANE.

func (*Runtime) Close 

func (rt *Runtime) Close() error

Close releases the runtime resources.

func (*Runtime) Compile 

func (rt *Runtime) Compile(opts CompileOptions) (*Kernel, error)

Compile compiles a model and returns a ready-to-evaluate Kernel.

func (*Runtime) CompileCount 

func (rt *Runtime) CompileCount() int64

CompileCount returns the number of compilations performed.

func (*Runtime) Info 

func (rt *Runtime) Info() DeviceInfo

Info returns the device information for this runtime.

type SharedEvent 

type SharedEvent struct{}

SharedEvent wraps an IOSurfaceSharedEvent for ANE↔GPU/CPU synchronization.

func NewSharedEvent 

func NewSharedEvent() (*SharedEvent, error)

func SharedEventFromPort 

func SharedEventFromPort(port uint32) (*SharedEvent, error)

func (*SharedEvent) Close 

func (e *SharedEvent) Close() error

func (*SharedEvent) Port 

func (e *SharedEvent) Port() uint32

func (*SharedEvent) Signal 

func (e *SharedEvent) Signal(value uint64)

func (*SharedEvent) SignaledValue 

func (e *SharedEvent) SignaledValue() uint64

func (*SharedEvent) Wait 

func (e *SharedEvent) Wait(value uint64, timeout time.Duration) bool

type SharedEventEvalOptions 

type SharedEventEvalOptions struct {
	DisableIOFencesUseSharedEvents bool // set kANEFDisableIOFencesUseSharedEventsKey
	EnableFWToFWSignal             bool // set kANEFEnableFWToFWSignal (keep false for ANE→Metal on physical hosts)
}

SharedEventEvalOptions configures shared event evaluation behavior.

type StateHandle 

type StateHandle struct{}

StateHandle manages KV cache state for stateful MIL models.

func NewStateHandle 

func NewStateHandle(_ *Kernel, _ int) *StateHandle

func (*StateHandle) Advance 

func (s *StateHandle) Advance(_ int)

func (*StateHandle) Close 

func (s *StateHandle) Close() error

func (*StateHandle) Kernel 

func (s *StateHandle) Kernel() *Kernel

func (*StateHandle) MaxSeq 

func (s *StateHandle) MaxSeq() int

func (*StateHandle) Position 

func (s *StateHandle) Position() int

func (*StateHandle) Remaining 

func (s *StateHandle) Remaining() int

func (*StateHandle) Reset 

func (s *StateHandle) Reset()

type TensorLayout 

type TensorLayout struct {
	Channels    int
	Width       int
	Height      int
	ElemSize    int
	RowStride   int
	PlaneStride int
}

TensorLayout describes the compiled model's memory layout for a single tensor.

func (TensorLayout) AllocSize 

func (l TensorLayout) AllocSize() int

func (TensorLayout) LogicalBytes 

func (l TensorLayout) LogicalBytes() int

func (TensorLayout) LogicalElements 

func (l TensorLayout) LogicalElements() int

type WeightFile 

type WeightFile struct {
	Path string
	Blob []byte
}

WeightFile describes a named MIL BLOBFILE entry.

Source Files

View all Source files

Directories

Path Synopsis
Package linear provides a cached linear (matrix multiply) operator backed by the Apple Neural Engine.
 Package linear provides a cached linear (matrix multiply) operator backed by the Apple Neural Engine.
Package mil generates MIL (Model Intermediate Language) programs and weight blobs for Apple Neural Engine compilation.
 Package mil generates MIL (Model Intermediate Language) programs and weight blobs for Apple Neural Engine compilation.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.