GitHub - mdaiter/ane: Reverse engineered the Apple Neural Engine, with working Python and Objective C samples

┌─────────────────────────────────────────────────────────────────┐
│                       User Application                           │
│                  (Core ML, Create ML, BNNS)                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────────────────┐    ┌─────────────────────────────┐ │
│  │   Espresso.framework    │    │ AppleNeuralEngine.framework │ │
│  │   ─────────────────     │    │ ─────────────────────────── │ │
│  │  • EspressoContext      │    │  • _ANEClient               │ │
│  │  • EspressoNetwork      │    │  • _ANEModel                │ │
│  │  • 40+ Pass_* classes   │    │  • _ANERequest              │ │
│  │  • CPU/GPU/ANE dispatch │    │  • _ANEDaemonConnection     │ │
│  └───────────┬─────────────┘    └──────────────┬──────────────┘ │
│              │                                  │                │
├──────────────┴──────────────────────────────────┴────────────────┤
│                     ANECompiler.framework                        │
│                     ─────────────────────                        │
│  • ANECConvLayerDesc (176 bytes)    • ANECSDPALayerDesc (8 bytes)│
│  • ANECPoolLayerDesc (96 bytes)     • ANECLinearLayerDesc (64 B) │
│  • ANECTensorDims (40 bytes)        • 30+ layer descriptors      │
├─────────────────────────────────────────────────────────────────┤
│                    XPC Transport Layer                           │
│            Service: com.apple.appleneuralengine                  │
├─────────────────────────────────────────────────────────────────┤
│                    aned (/usr/libexec/aned)                      │
│                    ───────────────────────                       │
│  • ANEProgramCreate()          • Model cache management          │
│  • ANEProgramInstanceCreate()  • Garbage collection              │
│  • Sandbox extension handling  • Telemetry                       │
├─────────────────────────────────────────────────────────────────┤
│                    ANE Hardware (M1/M2/M3+)                      │
│                    ───────────────────────                       │
│  • 16 neural engine cores      • Dedicated SRAM                  │
│  • Up to 15.8 TOPS (M1)        • IOSurface DMA                   │
└─────────────────────────────────────────────────────────────────┘

.mlmodelc/                      aned daemon                 Hardware
────────────                    ───────────                 ────────
     │                               │                          │
     │  1. _ANEModel create          │                          │
     ├──────────────────────────────►│                          │
     │                               │                          │
     │  2. compileModel: (XPC)       │                          │
     ├──────────────────────────────►│                          │
     │                               │  3. ANECompiler          │
     │                               ├─────────────────────────►│
     │                               │                          │
     │                               │  4. ANEProgramCreate()   │
     │                               ├─────────────────────────►│
     │                               │                          │
     │  5. Return program handle     │                          │
     │◄──────────────────────────────┤                          │
     │                               │                          │
     │  6. loadModel: (XPC)          │                          │
     ├──────────────────────────────►│                          │
     │                               │  7. Map to ANE memory    │
     │                               ├─────────────────────────►│
     │                               │                          │
     │  8. evaluateWithModel:        │  9. Execute on ANE       │
     ├──────────────────────────────►├─────────────────────────►│
     │                               │                          │

ane/
├── __init__.py          # Package exports, builds API tree for tooling
├── compiler.py          # ANECompiler.framework ctypes bindings
│                        #   - Layer descriptor structs
│                        #   - ANEC*Initialize() wrappers
│                        #   - Struct size probing
│
├── espresso.py          # Espresso model format parser
│                        #   - EspressoNet, EspressoLayer classes
│                        #   - Layer type documentation
│                        #   - CPU vs ANE model comparison
│
├── runtime.py           # Espresso/ANE runtime bindings
│                        #   - EspressoContext creation
│                        #   - EspressoNetwork loading
│                        #   - ObjC class introspection
│
├── xpc.py               # ANE XPC protocol documentation
│                        #   - _ANEDaemonConnection methods
│                        #   - _ANEClient methods
│                        #   - XPC operation categories
│
├── pbze.py              # PBZE (compressed espresso.net) decoder
│                        #   - LZFSE decompression via libcompression
│                        #   - Header parsing
│                        #   - Compression statistics
│
├── sample.py            # Example graph building code
│                        #   - SimpleANEGraph class
│                        #   - CNN and Transformer examples
│
├── tests/
│   └── test_ane.py      # Comprehensive pytest suite (623 lines)
│
└── helper/
    ├── ane_helper.m     # Objective-C helper for privileged ANE access
    ├── ane_helper.entitlements
    └── build.sh         # Build script

{
  "format_version": 200,
  "storage": "model.espresso.weights",
  "layers": [
    {
      "name": "conv1",
      "type": "convolution",
      "bottom": "input",
      "top": "conv1_output",
      "kernel_size": 3,
      "stride": 1,
      "pad": 1,
      "C": 64
    }
  ],
  "analyses": {},
  "properties": {}
}

Offset  Size  Description
──────  ────  ───────────
0x00    4     Magic: b'pbze'
0x04    4     Version (usually 0)
0x08    8     Unknown (header size?)
0x10    4     Uncompressed size (BIG ENDIAN!)
0x14    4     Unknown
0x18    4     Padding
0x1C    ...   LZFSE data (starts with b'bvx2')

Code   Operation          Code   Operation
────   ─────────          ────   ─────────
0      add                25     pow
1      sub                26     exp
2      mul                27     log
3      div                28     abs
4      floor_div          
                          101    select (ternary: a ? b : c)
10     max                105    less_than
11     min                106    less_equal
                          107    not_equal
20     sqrt               108    equal
21     rsqrt              109    greater_equal
22     square             110    greater_than
23     neg                
24     reciprocal         117    floor
                          118    ceil

Pass_fuse_conv_batchnorm          # Fuse BN into conv weights
Pass_fold_constants               # Constant folding
Pass_eliminate_dead_code          # DCE
Pass_fuse_activation              # Fuse relu/gelu into preceding op
Pass_optimize_transpose           # Eliminate redundant transposes
Pass_convert_to_ane_layout        # Convert to ANE memory layout
Pass_quantize_weights             # Weight quantization
Pass_split_large_tensors          # Split tensors for ANE tile size
... (and 30+ more)

Category              Layer Types
────────              ───────────
Attention/Transformer SDPA
Convolution           Conv, CrossCorrelation, DepthwiseConv
Pooling               Pool, GlobalPool, AdaptivePool
Normalization         Norm, BatchNorm, LayerNorm, GroupNorm, LRN
Linear/Matrix         Linear, MatrixMult, Einsum
Activation            Neuron, Softmax, LogSoftmax, Dropout
Reshape/Layout        Reshape, Transpose, Flatten, Unflatten, 
                      Concat, Split, Tile, Expand, Squeeze
Spatial               Resize, Pad, CropResize, Resample, 
                      AffineTransform, GridSample
Reduction             Reduction, TopK, Sort, ArgMax, ArgMin
Scatter/Gather        Gather, GatherND, Scatter, ScatterND
Misc                  Shape, Range, Random, Fill, 
                      RingBuffer, InputView, Copy

from ane import ANECompiler

ane = ANECompiler()
print(f"MPS Dialect Version: {ane.mps_dialect_version}")
print(f"MPS SPI Dialect Version: {ane.mps_spi_dialect_version}")
print(f"Validate Network Version: {ane.validate_network_version}")
print(f"Analytics Buffer Size: {ane.analytics_buffer_size}")

-[_ANEDaemonConnection compileModel:sandboxExtension:options:qos:withReply:]
-[_ANEDaemonConnection compiledModelExistsFor:withReply:]
-[_ANEDaemonConnection compiledModelExistsMatchingHash:withReply:]
-[_ANEDaemonConnection purgeCompiledModel:withReply:]

-[_ANEDaemonConnection loadModel:sandboxExtension:options:qos:withReply:]
-[_ANEDaemonConnection loadModelNewInstance:options:modelInstParams:qos:withReply:]
-[_ANEDaemonConnection unloadModel:options:qos:withReply:]

-[_ANEDaemonConnection prepareChainingWithModel:options:chainingReq:qos:withReply:]

-[_ANEDaemonConnection beginRealTimeTaskWithReply:]
-[_ANEDaemonConnection endRealTimeTaskWithReply:]

-createIOSurfaceWithExtraProperties:
-metalBufferWithDevice:
-setExternalStorage:ioSurface:
-nFrames
-bytesPerFrame
-totalBytes
// ... 21 methods total

/var/folders/<user_hash>/com.apple.aned/

+ (BOOL)hasANE;                    // Returns YES on Apple Silicon
+ (NSInteger)numANEs;              // Number of ANE devices (usually 1)
+ (NSInteger)numANECores;          // Number of cores (e.g., 16 for M1)
+ (NSString *)productName;         // "macOS"
+ (NSString *)buildVersion;        // e.g., "25B78"
+ (NSInteger)aneArchitectureType;  // Hardware architecture identifier
+ (NSInteger)aneSubType;           // Hardware subtype
+ (BOOL)isVirtualMachine;          // VM detection
+ (BOOL)isInternalBuild;           // Apple internal build detection
+ (BOOL)precompiledModelChecksDisabled;
+ (NSString *)bootArgs;            // Current boot arguments
+ (BOOL)isBootArgPresent:(NSString *)arg;
+ (BOOL)isBoolBootArgSetTrue:(NSString *)arg;

+ (NSString *)restrictedAccessEntitlement;      // "com.apple.aned.private.allow"
+ (NSString *)adapterWeightsAccessEntitlement;  // "com.apple.aned.private.adapterWeight.allow"
+ (NSString *)adapterWeightsAccessEntitlementBypassBootArg;  // "ane_skipAdapterWeightAccessCheck"
+ (NSString *)internalLibraryPath;              // "/AppleInternal/Library"
+ (NSString *)systemLibraryPath;                // "/System/Library"
// ... and many more

hasANE = 1
numANEs = 1
numANECores = 16
productName = macOS
buildVersion = 25B78
isVirtualMachine = 0
isInternalBuild = 0
precompiledModelChecksDisabled = 0

Client Process          aned Daemon           ANE Hardware
──────────────          ───────────           ────────────
     │                       │                     │
     │ Create IOSurface      │                     │
     ├──────────────────────►│                     │
     │                       │ Map to ANE          │
     │                       ├────────────────────►│
     │                       │                     │
     │ Write input data      │                     │
     ├───────────────────────┼────────────────────►│
     │                       │                     │
     │ Read output data      │                     │
     │◄──────────────────────┼─────────────────────┤

@interface EspressoProfilingLayerInfo : NSObject
@property (readonly) NSString *name;
@property (readonly) NSString *debug_name;
@property (readonly) double average_runtime;        // seconds
@property (readonly) int selected_runtime_engine;   // 0=CPU, 1=GPU, 2=ANE
@property (readonly) NSArray *runtimes;
@end

@interface EspressoProfilingNetworkANEInfo : NSObject
@property (readonly) uint64_t total_ane_time_ns;
@property (readonly) uint64_t ane_time_per_eval_ns;
@end

@interface _ANERequest : NSObject
@property uint32_t perfStatsMask;    // Bitmask for which stats to collect
@property (readonly) id perfStats;
@property (readonly) NSArray *perfStatsArray;
@end

from ane import SimpleANEGraph

# Create graph builder
graph = SimpleANEGraph()

# Input: (batch=1, channels=3, height=224, width=224)
graph.add_conv2d("conv1", (1, 3, 224, 224), 
                 out_channels=64, kernel_size=7, stride=2, padding=3)
# Output: (1, 64, 112, 112)

graph.add_pool2d("pool1", (1, 64, 112, 112), kernel_size=3, stride=2)
# Output: (1, 64, 56, 56)

graph.add_conv2d("conv2", (1, 64, 56, 56), 
                 out_channels=128, kernel_size=3, padding=1)
# Output: (1, 128, 56, 56)

graph.add_conv2d("conv3", (1, 128, 56, 56), 
                 out_channels=256, kernel_size=3, padding=1)
# Output: (1, 256, 56, 56)

graph.add_pool2d("pool2", (1, 256, 56, 56), kernel_size=2, stride=2)
# Output: (1, 256, 28, 28)

graph.add_linear("fc1", input_features=256*28*28, output_features=1024)
graph.add_linear("fc2", input_features=1024, output_features=1000)
graph.add_softmax("softmax", (1, 1000))

print(graph.summary())

ANE Computation Graph
============================================================

conv1 (conv2d)
  Input:  (1, 3, 224, 224)
  Output: (1, 64, 112, 112)
  Desc:   176 bytes
  Kernel: 7x7
  Stride: 2x2
  Pad:    3,3

pool1 (pool2d)
  Input:  (1, 64, 112, 112)
  Output: (1, 64, 56, 56)
  Desc:   96 bytes
  Kernel: 3x3
  Stride: 2x2

...

============================================================
Total layers: 8
Total descriptor bytes: 680

from ane import build_transformer_attention

graph = build_transformer_attention()
print(graph.summary())

ANE Computation Graph
============================================================

proj_qkv (linear)
  Input:  (512, 512, 1, 1)
  Output: (512, 1536, 1, 1)
  Desc:   64 bytes

attention (sdpa)
  Input:  (1, 8, 512, 64)
  Output: (1, 8, 512, 64)
  Desc:   8 bytes              <-- Native transformer attention!

proj_out (linear)
  Input:  (512, 512, 1, 1)
  Output: (512, 512, 1, 1)
  Desc:   64 bytes

============================================================
Total layers: 3
Total descriptor bytes: 136

from ane import (
    create_espresso_cpu_context,
    load_espresso_network,
    get_network_layer_count,
    EspressoNet,
)

# Method 1: Direct runtime loading (CPU only without entitlements)
ctx = create_espresso_cpu_context()
print(f"Context: {hex(ctx)}")

model_path = "/path/to/model.espresso.net"
net = load_espresso_network(model_path, ctx)
print(f"Network: {hex(net)}")
print(f"Layers: {get_network_layer_count(net)}")

# Method 2: Parse the file directly
model = EspressoNet.from_file(model_path)
print(f"Format version: {model.format_version}")
print(f"Layer types: {model.layer_type_counts()}")

# Analyze inner_product layers for quantization
for ip in model.get_inner_product_info():
    print(f"  {ip['name']}: {ip['nB']}x{ip['nC']}, "
          f"quant={ip['quantization_mode']}, lookup={ip['is_lookup']}")

from ane import decode_espresso_net, get_pbze_stats, is_pbze_file

path = "/System/Library/SomeFramework/model.espresso.net"

# Check format
if is_pbze_file(path):
    stats = get_pbze_stats(path)
    print(f"Compressed size: {stats['compressed_size']} bytes")
    print(f"Uncompressed size: {stats['uncompressed_size']} bytes")
    print(f"Compression ratio: {stats['compression_ratio']:.2f}x")

# Decode (handles both JSON and PBZE automatically)
data = decode_espresso_net(path)
print(f"Layers: {len(data['layers'])}")

# Build and sign
cd helper
./build.sh "Developer ID Application: Your Name (TEAMID)"

# Check status
echo '{"cmd": "status"}' | ./ane_helper
# {"ok":true,"client":true,"model_count":0,"model_ids":[]}

# Compile a model
echo '{"cmd": "compile", "model_path": "/path/to/model.mlmodelc"}' | ./ane_helper
# {"ok":true,"model_id":"ABC123","state":1}

# Load into ANE memory
echo '{"cmd": "load", "model_id": "ABC123"}' | ./ane_helper
# {"ok":true,"model_id":"ABC123","program_handle":12345}

# Unload
echo '{"cmd": "unload", "model_id": "ABC123"}' | ./ane_helper
# {"ok":true}

Pass_add_fp16_fp32_conversions
Pass_batch_matmul_transpose_fusion
Pass_broadcast_optimization
Pass_canonicalize_ops
Pass_constant_folding
Pass_convert_gather_to_slice
Pass_convert_to_ane_layout
Pass_dead_code_elimination
Pass_decompose_complex_ops
Pass_eliminate_identity_ops
Pass_eliminate_redundant_transpose
Pass_fold_constants
Pass_fuse_activation
Pass_fuse_add_mul
Pass_fuse_bias
Pass_fuse_conv_batchnorm
Pass_fuse_conv_bias
Pass_fuse_elementwise
Pass_fuse_gelu
Pass_fuse_layernorm
Pass_fuse_linear_ops
Pass_fuse_matmul_add
Pass_fuse_mul_add
Pass_fuse_pad_conv
Pass_fuse_reshape_transpose
Pass_insert_copies_for_ane
Pass_legalize_for_ane
Pass_lower_to_ane_ops
Pass_optimize_memory_layout
Pass_optimize_reshape_chain
Pass_optimize_transpose
Pass_propagate_shapes
Pass_quantize_weights
Pass_remove_unused_outputs
Pass_replace_div_with_mul
Pass_simplify_arithmetic
Pass_split_large_tensors
Pass_tensor_parallel_partition
Pass_tile_for_ane
Pass_vectorize_ops

// Lifecycle
- (instancetype)initWithRestrictedAccessAllowed:(BOOL)allowed;

// Compilation
- (BOOL)compileModel:(id)model options:(id)opts qos:(int)qos error:(NSError**)err;
- (BOOL)compiledModelExistsFor:(id)model;
- (BOOL)compiledModelExistsMatchingHash:(NSData*)hash;
- (BOOL)purgeCompiledModel:(id)model;

// Loading
- (BOOL)loadModel:(id)model options:(id)opts qos:(int)qos error:(NSError**)err;
- (BOOL)loadModelNewInstance:(id)model options:(id)opts modelInstParams:(id)params qos:(int)qos error:(NSError**)err;
- (BOOL)loadRealTimeModel:(id)model options:(id)opts qos:(int)qos error:(NSError**)err;
- (BOOL)unloadModel:(id)model options:(id)opts qos:(int)qos error:(NSError**)err;

// Evaluation
- (BOOL)evaluateWithModel:(id)model options:(id)opts request:(id)req qos:(int)qos error:(NSError**)err;
- (BOOL)evaluateRealTimeWithModel:(id)model options:(id)opts request:(id)req error:(NSError**)err;

// Memory
- (BOOL)mapIOSurfacesWithModel:(id)model request:(id)req cacheInference:(BOOL)cache error:(NSError**)err;
- (void)unmapIOSurfacesWithModel:(id)model request:(id)req;

// Chaining
- (BOOL)prepareChainingWithModel:(id)model options:(id)opts chainingReq:(id)req qos:(int)qos error:(NSError**)err;

// Initialization
- (instancetype)initWithModelAtURL:(NSURL*)url 
                               key:(NSString*)key
                  identifierSource:(int)src
              cacheURLIdentifier:(NSString*)cacheId
                 modelAttributes:(id)attrs
                  standardizeURL:(BOOL)standardize;
- (instancetype)initWithModelIdentifier:(id)identifier;

// Properties
@property (readonly) NSURL *modelURL;
@property (readonly) NSURL *sourceURL;
@property (readonly) NSString *UUID;
@property (readonly) NSString *key;
@property (readonly) int state;  // 1 = created/unloaded
@property (readonly) uint64_t programHandle;
@property (readonly) uint64_t intermediateBufferHandle;
@property (readonly) int queueDepth;
@property (readonly) uint32_t perfStatsMask;
@property (readonly) id mpsConstants;

// Initialization
- (instancetype)initWithInputs:(NSArray*)inputs
                  inputIndices:(NSArray*)inputIndices
                       outputs:(NSArray*)outputs
                 outputIndices:(NSArray*)outputIndices
                 weightsBuffer:(id)weights
                     perfStats:(id)stats
                procedureIndex:(int)procIdx
                  sharedEvents:(id)events
             transactionHandle:(uint64_t)handle;

// Properties
@property (readonly) NSArray *inputArray;
@property (readonly) NSArray *inputIndexArray;
@property (readonly) NSArray *outputArray;
@property (readonly) NSArray *outputIndexArray;
@property (readonly) id weightsBuffer;
@property (readonly) int procedureIndex;
@property (readonly) id perfStats;
@property (readonly) NSArray *perfStatsArray;
@property (copy) void (^completionHandler)(BOOL, NSError*);
@property (readonly) id sharedEvents;
@property (readonly) uint64_t transactionHandle;

# Run all tests
pytest tests/test_ane.py -v

# Run specific test class
pytest tests/test_ane.py::TestANECompiler -v

# Run with coverage
pytest tests/test_ane.py --cov=ane --cov-report=term-missing

// Objective-C
MLModelConfiguration *config = [[MLModelConfiguration alloc] init];
config.computeUnits = MLComputeUnitsAll;  // Enables ANE

MLModel *model = [MLModel modelWithContentsOfURL:modelURL 
                                   configuration:config 
                                           error:&error];

# Python with coremltools
import coremltools as ct
model = ct.models.MLModel("model.mlpackage", compute_units=ct.ComputeUnit.ALL)

// Get ANE device info
Class deviceClass = NSClassFromString(@"MLNeuralEngineComputeDevice");
id device = [deviceClass performSelector:@selector(physicalDevice)];
NSInteger cores = [[device valueForKey:@"totalCoreCount"] integerValue];
// Returns 16 on M3 Pro