Multi-target ports + unified bench infrastructure

[navado]

Multi-target ports + unified bench infrastructure

Adds first-class build paths for Apple Silicon, i.MX 8/93/95 (NXP
NPU), and ESP32-P4 (Espressif RISC-V MCU), plus a cross-platform
benchmark tool and a unified coverage matrix. Default make is
unchanged for existing x86 users — every new path is opt-in.

Four commits, each self-contained and amending its own section in the
new docs/implementation.md:

83aeee7  Add ESP32-P4 ESP-IDF component + MIPI-CSI camera example
6bc5f99  Add i.MX NPU library (TFLite + Ethos-U65 / VxDelegate / XNNPACK)
f75fd64  Add Apple Silicon perf paths: Accelerate (AMX), SME (M4+), Core ML (ANE)
7afb4f7  Add unified benchmark tooling + AArch64 NEON foundation

What's added

1. Bench foundation (7afb4f7) — also makes make work on ARM hosts

• tools/bench.c — cross-platform synthetic latency bench. md/csv/json
  output. Same source compiles on macOS arm64/x86, Linux aarch64, future
  i.MX targets.
• tools/bench_camera_mac.swift + make bench-camera — live AVFoundation
  camera benchmark. --summary mode emits one CSV row in the same schema
  as facex-bench so the two can be merged into one table.
• scripts/bench_all.sh — sweeps build-flag combinations, emits unified
  Markdown comparison.
• scripts/test_all.sh — single-host test harness; topic commits amend
  with their own checks (51/51 PASS on M2).
• AArch64 build foundation: Makefile arch detection via uname -m,
  src/threadpool_pthread.c (futex/WaitOnAddress aren't portable),
  FACEX_NO_INT8 flag for the engine, hand-written NEON kernels for
  matmul_fp32_packed{,_bias,_bias_gelu} (output byte-identical to
  scalar within ULP), and a fix for the column-panel scalar fallbacks
  that were silently wrong on every non-x86 host.

2. Apple Silicon perf paths (f75fd64) — opt-in, never default

Build	Adds	Measured speedup
make ACCELERATE=1	cblas_sgemm via Accelerate.framework (AMX)	-22% embed / -13% e2e on M2
make SME=1	M4+ FMOPA outer-product kernel; auto-disabled on M1-M3	n/a (compiles cleanly; not directly hardware-tested)
make COREML=1	Obj-C bridge loading .mlpackage for Apple Neural Engine	n/a (compile + link verified)
make mac-universal	Cross-compiled fat arm64 + x86_64 archive	each slice contains real arch-specific SIMD

Each opt-in dispatch is gated at compile time AND runtime via a
self-check (e.g. SME runs a tiny FMOPA-vs-scalar consistency test and
disables itself on output divergence). Critical: -march=armv9-a+sme
is applied per-file to transformer_ops_sme.c only — applying it
globally would let clang auto-vectorize plain C using SVE/SME and trap
on M1/M2/M3.

3. i.MX NPU library (6bc5f99) — separate libfacex_npu.{so,dylib}

Make target	SoC	NPU	Delegate
make imx-npu	host (dev)	XNNPACK fallback	(built into TFLite)
make imx93 SDK=…	i.MX 93	Arm Ethos-U65	libethosu_delegate.so
make imx95 SDK=…	i.MX 95	Arm Ethos-U65	libethosu_delegate.so
make imx8mp SDK=…	i.MX 8M Plus	VeriSilicon VIP9000	libvx_delegate.so

src/backend_tflite.c is a TFLite C-API wrapper with a dlopen-based
delegate loader (vendor .sos aren't a hard dep — auto-fallback to
XNNPACK if missing). One source path, three deployment targets. New
public API in include/facex_npu.h, mirrors facex.h shape.

Detector path is intentionally -ENOSYS. Anchor decode + NMS for
arbitrary YuNet/SCRFD topology is too fragile to ship blind. The
recommended deployment is the hybrid pipeline: CPU detect via
libfacex.a, NPU embed via libfacex_npu.so. ~80% of the perf
benefit, none of the post-processing risk. Documented in
docs/imx_npu.md.

Offline tooling: tools/onnx_to_tflite.py (PyTorch/ONNX → INT8 TFLite)
and tools/compile_vela.sh (Arm Vela for Ethos-U65).

4. ESP32-P4 ESP-IDF component (83aeee7)

components/facex/ (IDF wrapper) + examples/esp32p4_camera/ (full
runnable IDF project).

The MIPI-CSI capture path is complete and runnable — follows the
official ESP-IDF camera_driver recipe verbatim (LDO 2.5 V on the CSI
PHY, SCCB I2C, esp_cam_sensor_detect, esp_cam_new_csi_ctlr,
IRAM-safe callbacks, PSRAM frame buffer ring, capture task that
downscales RGB565 → RGB888 and calls the FaceX backend, requeues).
Logs FPS + per-detection latency once per second.

The face-detection backend is a Kconfig three-way choice:

• stub (default) — synthetic deterministic face per frame for
  bring-up. Works on the EV-Board today.
• native — links the existing C engine. Compiles, runs, but at
  1-3 s/frame the EdgeFace-XS model is too large for production on
  P4. Provided for evaluation only.
• espnn — reserved Kconfig slot. Production target needs a
  distilled EdgeFace-Nano (~300 K params, 64×64 input, 256-d
  embedding, no XCA attention) plus an ESP-NN backend (PIE-SIMD INT8).
  Not in this PR — model + kernel work is its own milestone.

Honest scope: the camera + dispatch bridge ships now; production-fit
model is the follow-up. Once it exists, only the Kconfig backend
toggle changes; everything else in this commit stays.

Coverage at a glance (full table in docs/coverage_matrix.md)

Configuration	Compiles	Runs end-to-end	Tested on
Default make (Apple Silicon arm64 / NEON)	✅	✅	M2, macOS
make ACCELERATE=1 (AMX)	✅	✅	M2
make SME=1 (M4+ FMOPA)	✅	🧪 inert on M2 (sysctl FEAT_SME=0); self-check guards M4 correctness	M2 (compile + isolation only)
make COREML=1 (ANE bridge)	✅	🧪 missing-.mlpackage smoke passes; ANE dispatch needs ONNX export	M2 (compile + link + error path)
make mac-universal (fat archive)	✅	✅ both slices contain arch-specific SIMD	M2
make imx-npu / imx93 / imx95 / imx8mp	🧪 (against TFLite header stubs)	🚫 needs vendor SDK + EVK	mac-m2 (syntax only)
ESP-IDF component + camera example	🧪 (against IDF header stubs)	🚫 needs IDF + P4-Function-EV-Board	mac-m2 (syntax only)
Existing x86 / WASM paths	upstream	upstream	unchanged

scripts/test_all.sh runs every check that's executable on the host:
51/51 PASS on M2. Topic commits each register their own checks so
the runner stays exhaustive as features land.

🧪 / 🚫 honesty markers: where I couldn't validate on hardware (M4,
i.MX EVK, P4 dev kit), the code follows the documented vendor APIs
(esp_cam_ctlr_*, TFLite C-API + delegate ABI, ACLE 2024 SME
intrinsics). Self-checks at runtime guard correctness for the SME
path. Bring-up checklists are documented in docs/{mac,imx_npu,esp32p4}.md.

Benchmark results (M2, n=100, scripts/bench_all.sh)

Build	Active backends	Embed median	E2E median
default	NEON	4.59 ms	8.46 ms
ACCELERATE=1	Accelerate(AMX) + NEON	3.54 ms	7.52 ms
SME=1	NEON (SME inert on M2)	4.57 ms	8.63 ms
SME=1 ACCELERATE=1	Accelerate(AMX) + NEON	3.52 ms	7.49 ms

Same \|\|emb\|\|² = 0.0756, same self-similarity 1.0000, same bbox
across all four — backend choice never changes the embedding bytes
beyond ULP.

WASM (Node.js, node wasm/bench.js): 5.27 ms median, 190 fps.
Embedding output matches native byte-for-byte.

Reproduce locally

bash download_weights.sh                       # pulls data/edgeface_xs_fp32.bin
make                                           # default build (NEON on ARM, AVX2 on x86)
make test                                      # golden test
scripts/test_all.sh                            # full local sweep (51 checks)
scripts/bench_all.sh --iters 200 --warmup 50   # build-flavour comparison table

# Mac-only opt-ins:
make ACCELERATE=1 mac-test                     # AMX
make SME=1 mac-test                            # M4+ SME
make COREML=1                                  # ANE bridge
make mac-universal                             # fat arm64 + x86_64

Compatibility / risk

• Default build is unchanged. x86 users see the same Makefile
  paths, same flags, same artifacts.
• No new mandatory dependencies. libfacex.a still has zero
  external runtime deps (otool -L → libSystem only on macOS, libc
  • libpthread on Linux). NPU build is opt-in via
    FACEX_BACKEND_TFLITE; Mac perf paths are opt-in via per-flag
    build vars.
• No API breaks. Existing public C API is untouched. New surfaces
  are additive: include/facex_npu.h, include/facex_coreml.h,
  include/facex_backend.h.
• examples/example.c has a 1-line update for the existing 3-arg
  facex_init signature — was orphaned in upstream relative to the
  current API.

What's NOT in this PR

• EdgeFace-Nano distilled model (sized for ESP32-P4)
• ESP-NN-based FaceX backend (production path for P4)
• Hardware-validated runs on i.MX 8M Plus / 93 / 95 EVKs
• Hardware-validated SME runs on M4 / M5
• Core ML .mlpackage artefact (needs an EdgeFace ONNX export not in
  this repo)
• WASM rebuild from source (uses pre-built wasm/*.wasm; no make wasm target wired)

Each of these is documented in docs/implementation.md with the
unblock path for whoever picks it up next.

Files at a glance

44 files changed, 6457 insertions(+), 30 deletions(-)

docs/
  benchmarking.md          how to bench (which-tool-when matrix)
  coverage_matrix.md       compile/static/e2e per (target × backend × flag)
  esp32p4.md               ESP32-P4 build, deploy, troubleshooting
  imx_npu.md               i.MX NPU deployment + bring-up checklist
  implementation.md        per-topic implementation snapshot (this doc)
  mac.md                   Apple Silicon build modes + perf reference

src/
  backend_accelerate.c     AMX cblas wrapper                       [Mac]
  backend_coreml.m         ARC Obj-C bridge for ANE / .mlpackage   [Mac]
  backend_tflite.c         TFLite + delegate loader                [i.MX]
  cpu_features.{h,c}       sysctl-based runtime probe              [Mac]
  threadpool_pthread.c     pthread+condvar pool                    [Bench]
  transformer_ops_sme.c    M4+ FMOPA matmul                        [Mac]

include/
  facex_backend.h          pluggable backend vtable                [i.MX]
  facex_coreml.h           Core ML public C API                    [Mac]
  facex_npu.h              NPU public C API                        [i.MX]

tools/
  bench.c                  cross-platform synthetic bench          [Bench]
  bench_camera_mac.swift   AVFoundation camera bench               [Bench]
  build_bench_camera_mac.sh swiftc invoker                         [Bench]
  compile_vela.sh          Vela compiler wrapper                   [i.MX]
  export_coreml.py         ONNX → .mlpackage                       [Mac]
  onnx_to_tflite.py        ONNX → INT8 .tflite                     [i.MX]

scripts/
  bench_all.sh             build-flavour sweep → comparison table  [Bench]
  test_all.sh              local test harness (51 checks)          [Bench]

components/facex/          ESP-IDF component                       [ESP32]
examples/esp32p4_camera/   Runnable IDF MIPI-CSI camera example    [ESP32]
tests/test_mac.c           Mac smoke + latency stats               [Mac]
tests/test_imx_npu_compile.c  NPU API smoke                        [i.MX]

Bisectability

Every commit builds clean on M2 (make succeeds, scripts/test_all.sh
passes its own commit's checks). The four are also intentionally
decoupled: Mac, i.MX, and ESP32 don't depend on each other; they all
sit on the Bench foundation.