Skip to content

Add Windows ARM64 and Qualcomm Hexagon NPU support - #40

Open
roozbehid wants to merge 2 commits into
pwilkin:mainfrom
roozbehid:qualcomm-npu
Open

Add Windows ARM64 and Qualcomm Hexagon NPU support#40
roozbehid wants to merge 2 commits into
pwilkin:mainfrom
roozbehid:qualcomm-npu

Conversation

@roozbehid

Copy link
Copy Markdown

Summary

This adds native Windows ARM64 support and makes the TRELLIS.2 pipeline usable with
partial-coverage accelerators such as the Qualcomm Hexagon NPU.

The implementation adds:

  • Native Windows ARM64 CPU, Vulkan, and Hexagon build support.
  • Explicit backend selection with --backend HTP|Vulkan|CPU.
  • A device-enumeration utility with optional initialization checks.
  • Multi-backend ggml scheduling for unsupported-operation fallback.
  • Optional HTP -> Vulkan -> CPU scheduling with --vulkan-fallback.
  • Backend-specific weight repacking support.
  • CPU thread configuration for both primary and fallback CPU backends.
  • HTP-specific fast FlashAttention defaults with an F32 opt-out.
  • Progress heartbeats, graph timings, and backend diagnostics.
  • Support for the trimmed Windows Hexagon SDK 6.6 package.

Companion ggml correctness/build PR: ggml-org/ggml#1601

This Trellis PR deliberately leaves the ggml submodule revision unchanged. The companion
ggml changes are required for the tested Qualcomm HTP F16 and Adreno Q4 Vulkan behavior
until they are incorporated into the submodule.

Backend selection

On Snapdragon systems, Vulkan and Hexagon can both register as GPU-class devices.
Selecting based only on reported memory is therefore ambiguous.

The new option chooses the backend explicitly:

trellis-cli.exe input.png output.glb `
  --models models\q4 `
  --backend HTP `
  --sched on `
  --verbose

trellis-devices --init lists registered backends and verifies that each device can
initialize.

Multi-backend scheduling

The Hexagon backend intentionally supports only a subset of ggml operations. Graphs now
run through ggml_backend_sched when HTP is selected, allowing unsupported nodes to
execute on fallback backends.

Default HTP order:

HTP -> CPU

Optional mixed-backend order:

HTP -> Vulkan -> CPU

Enable the latter with:

--vulkan-fallback

The equivalent TRELLIS_VULKAN_FALLBACK=1 environment variable remains available for
existing automation.

FlashAttention policy

HTP defaults to F16 K/V with fast accumulation. Other backends retain BF16 K/V with F32
accumulation by default.

Overrides:

  • --fa-fast: force the fast F16 path
  • --fa-f32: force BF16 K/V with F32 accumulation
  • --no-fa: disable FlashAttention

A 12-step res512 correctness gate produced:

Metric HTP BF16/F32 HTP F16 fast
Total 2482.3 s 702.8 s
Sparse flow 2005.7 s 494.5 s
Shape flow 259.9 s 101.1 s
Texture flow 157.8 s 61.9 s
Sparse voxels 484 484

This is a 3.53x end-to-end improvement. Deterministic renders preserved the same
silhouette, topology, and material placement.

HTP + Vulkan fallback result

A matching res512, one-step, geometry-only A/B produced:

Configuration Total
HTP + CPU 87.7 s
HTP + Vulkan + CPU 54.5 s

The mixed configuration was 37.9% faster. Both runs produced byte-identical voxel PLY
output. Vulkan fallback remains opt-in pending testing across more inputs and full sampler
counts.

Windows ARM64 build

The build helper imports the Visual Studio ARM64 environment and configures clang for
arm64-pc-windows-msvc.

scripts\build-arm64.ps1 -Backend cpu
scripts\build-arm64.ps1 -Backend vulkan
scripts\build-arm64.ps1 -Backend hexagon `
  -HexagonSdk C:\Qualcomm\Hexagon_SDK\6.6.0.0

The trimmed Hexagon SDK described in the official llama.cpp Windows Snapdragon
documentation is supported. The script reads the Hexagon Tools path from
hexagon_sdk.json and supplies the compatibility values required by the current ggml
Hexagon CMake integration.

Windows still requires properly signed HTP Ops libraries and catalog files before the NPU
driver will load them.

Validation

Tested on:

  • ASUS Zenbook A16 UX3607OA
  • Snapdragon X2 Elite Extreme X2E94100
  • Adreno X2-90
  • Hexagon v81 NPU
  • 48 GB unified memory
  • Windows 11 ARM64
  • Hexagon SDK 6.6.0.0

Build validation after rebasing onto current pwilkin/main:

  • Native ARM64 CPU build: passed, 77 targets
  • Native ARM64 Hexagon + Vulkan build: passed, 103-target rebuild
  • All HTP skels through v81 available
  • Vulkan and CPU device initialization passed
  • Failed/unsigned HTP initialization is now reported cleanly by trellis-devices rather
    than asserting

Scope and cleanup

The branch contains no port diary, machine-specific status file, temporary probe
executable, hard-coded developer path, or ggml submodule change.

@pwilkin

pwilkin commented Aug 21, 2026

Copy link
Copy Markdown
Owner

Okay, this is really nice. Your results with the fast attention path suggest that there might be a possibility for fast attention on other platforms if we solve the precision issues, that would make runs much faster. I'll try to merge ASAP.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants