npunlock: Schrijf en voer aangepaste C-kernels uit voor Intel Core Ultra NPU's

De huidige implementatie is geverifieerd op Windows x64 met Meteor Lake / NPU3720.

Recente doorbraak (23-09-2026): Eén native grafiek kan onafhankelijke FP32-unaire en FP16-binaire aangepaste vertakkingen uitvoeren; een expliciete ACT-groep preflight handelt de herordening van vertakkingen door de compiler af.

Snel voorbeeld

Dit volledige FP32 GELU-voorbeeld bedraagt de C-kernel in Python, plaatst deze in een NPU-grafiek en controleert het resultaat tegen NumPy. De gebundelde npunlock/npu3720_kernel.h target-header levert de NPU3720-aanroeping en tensor-adres helpers. De geteste MoviTools-toolchain maakt de meeste conventionele libm-functies beschikbaar voor kernels zonder dat <math.h> hoeft te worden geïncludeerd; dit voorbeeld roept tanhf rechtstreeks aan. Raadpleeg de mlibm.a symboolinventaris voor de waargenomen kandidaten.

import numpy as np
import npunlock as npu

npu.configure(movi_dll_dir=r"C:\path\to\MVC_DEPEND")

gelu_c: bytes = b"""
#define MLIBM_DEFINE_LINK_COMPAT 1
#include <npunlock/npu3720_kernel.h>

void controlled_act(unsigned layerParams) {
    act_abi_invocation invocation;
    ACT_ABI_LOAD_INVOCATION32_OR_RETURN(layerParams, invocation);
    const float *in = ACT_ABI_INPUT_PTR32(const float, invocation, 0u);
    float *out = ACT_ABI_OUTPUT_PTR32(float, invocation, 1u);
    const float SQRT_2_DIV_PI = 0.7978845608028654f;

    for (unsigned i = 0; i < invocation.element_count; ++i) {
        float x = in[i];
        float w = x + 0.044715f * x * x * x;
        w = tanhf(w * SQRT_2_DIV_PI);
        out[i] = 0.5f * x * (1.0f + w);
    }
}
"""

N = 2048
x = npu.input("x", shape=(1, N), dtype="f32")
y = npu.custom(
    x,
    source=gelu_c,
    carrier="Abs",
    _name="y",
)

program = npu.compile(npu.Graph(inputs=[x], outputs=[y], name="gelu_f32_example"))
input_value = np.linspace(-4, 4, N, dtype=np.float32).reshape(1, -1)
output = program.run({"x": input_value})["y"]

reference = 0.5 * input_value * (
    1.0
    + np.tanh(
        np.sqrt(2.0 / np.pi)
        * (input_value + 0.044715 * input_value**3)
    )
)

print(f"maximum absolute error: {np.max(np.abs(output - reference)):g}")

Dezelfde code is beschikbaar als het uitvoerbare FP32 GELU voorbeeld. Zie ook de FP16 GELU en multi-layer two-input voorbeelden, plus een mixed-precision grafiek met unaire en binaire aangepaste vertakkingen.

Waarom npunlock?

De normale NPU-software van Intel accepteert grafieken die zijn samengesteld uit operaties die de compiler ondersteunt; er is geen publieke workflow beschikbaar om een C-implementatie voor een operatie aan te leveren. De ACT-SHAVE-processors van de NPU zijn echter programmeerbaar en voeren softwarekernels uit. npunlock maakt deze processors bruikbaar voor compatibele aangepaste grafiekoperaties, terwijl de compiler en driver van Intel behouden blijven voor de omliggende grafiek en hardware-executie.

Vereisten

  • Windows x64
  • Meteor Lake / Intel NPU3720
  • Een geïnstalleerde Intel NPU-driver voor het apparaat
  • Python 3.10 of nieuwer
  • CMake 3.24 of nieuwer en een geïnstalleerde MSVC-toolchain voor broninstallatie
  • De uitgepakte MoviTools MVC_DEPEND toolchain voor aangepaste C-compilatie

OpenVINO is niet vereist als runtime, Python-pakket of compiler-frontend. npunlock genereert wel IR in OpenVINO-formaat voor de geïnstalleerde Intel-driver.

Installatie

npunlock wordt momenteel geïnstalleerd vanuit een source checkout:

python -m pip install .

De build bundelt npunlock.dll en npunlock_worker.exe in het Python-pakket, waardoor normaal Python-gebruik geen apart native pad vereist.

MoviTools verkrijgen

Voor de compilatie van aangepaste C-code wordt gebruikgemaakt van Intel/Movidius MoviTools. npunlock distribueert of downloadt deze niet.

Een MoviTools-pakket dat is geverifieerd als werkend, is gevonden in een legacy Lenovo-driverpakket. Raadpleeg "Getting MoviTools" voor de officiële download, hash, extractiecommando en de verwachte lay-out.

Pak de MVC_DEPEND payload uit het oudere Intel NPU-driverpakket 31.0.100.1688 van Lenovo. Let op: installeer deze driver niet en downgrade ook niet naar deze driver. Alleen de gebundelde MoviTools zijn nodig.

Een voorbeeld uitvoeren

Verwijs npunlock naar de uitgepakte MVC_DEPEND root en voer GELU uit:

$env:NPUNLOCK_MOVITOOLS_DIR = 'C:\path\to\MVC_DEPEND'
python examples\example_gelu.py

Het voorbeeld draait op de NPU en rapporteert de maximale fout ten opzichte van een NumPy-referentie.

Wat momenteel werkt

  • Het compileren van door de gebruiker geschreven C naar ACT-SHAVE machinecode.
  • Het uitvoeren van aangepaste kernels binnen Intel NPU-grafieken.
  • Statische dense FP16 unaire en two-input aangepaste kernels.
  • Een geverifieerd unair FP32-pad.
  • Eén grafiek die onafhankelijke FP32-unaire en FP16-binaire aangepaste vertakkingen bevat.
  • Niet-lineaire wiskunde zoals GELU en tanhf.
  • Herbruikbare NumPy-compatibele host/NPU gedeelde input- en output-buffers.
  • Python, CLI en native C API's.

Huidige beperkingen

De ondersteuning is experimenteel en momenteel beperkt tot:

  • Windows x64, Meteor Lake / NPU3720.
  • Statische shapes.
  • Compatibele ACT-carriers.
  • Bekende tensor-layouts.

Verbonden mixed-precision conversiegroepen zijn nog niet patch-discoverable; het geverifieerde mixed-precision voorbeeld maakt gebruik van onafhankelijke vertakkingen. Andere NPU-generaties zijn niet geverifieerd. Zie "Current limitations" voor de volledige compatibiliteitsgrenzen.

Help bij het testen van Linux en nieuwere NPU's

Heb je een NPU3720 Linux-systeem of een nieuwere Intel NPU? Bijdragen zijn welkom. Twee routes lijken veelbelovend maar zijn nog niet getest:

  1. Een gepatchte NPU3720-grafiek die op Windows is geproduceerd, kan mogelijk op Linux draaien omdat de NPU-firmware de aangepaste machinecode uitvoert. Het bouwen van SHAVE-code op Linux zou echter een manier vereisen om de Windows MoviTools DLL's te laden.
  2. Nieuwere NPU's kunnen mogelijk het bestaande 3720xx SHAVE-image uitvoeren, of een ouder OEM-driverpakket voor die generatie kan matching MoviTools-componenten leveren.

Beide benaderingen vereisen hardwarevalidatie, driver/firmware-versiegegevens en een output-vergelijking met een host-oracle. Als je een van deze paden kunt testen, zijn feedback, foutrapporten en codebijdragen welkom. Zie "Porting to Linux and newer NPUs" voor de hypothesen, kanttekeningen en een voorgesteld testplan.

Documentatie

  • Getting MoviTools — De compiler-toolchain verkrijgen zonder de legacy-driver te installeren.
  • Python API — Grafieken construeren, compileren en uitvoeren vanuit Python.
  • Writing custom kernels — C entry point, tensor contract en voorbeelden.
  • How npunlock works — Grafiekcompilatie en integratie van aangepaste kernels.
  • Reverse-engineering breakthroughs — De experimenten en ontdekkingen die aangepaste kernels mogelijk maakten.
  • From model to machine code — Stap-voor-stap lowering en de betrokken componenten.
  • Intel NPU architecture — Overzicht van DPU en ACT-SHAVE.
  • Current limitations — Geverifieerde hardware en ABI-scope.
  • Porting to Linux and newer NPUs — Experimentele routes en bijdragegids.
  • Development and native APIs — CMake, testen, verpakken, CLI en C-interfaces.
  • Volledige documentatie-index.

Waarschuwing over AI-gebruik

Een opmerking over het gebruik van AI: ik heb AI gebruikt tijdens het bouwen van dit project voor scaffolding, repetitief implementatiewerk, het omzetten van mijn reverse-engineering resultaten in georganiseerde documentatie en het verbeteren van mijn Engels. De reverse engineering, experimenten, debugging en technische conclusies zijn voortgekomen uit handmatig werk.

Licentie

npunlock is gelicentieerd onder de Apache License 2.0. MoviTools en de Intel/Movidius-bibliotheken zijn externe propriëtaire afhankelijkheden en worden niet gedekt of gedistribueerd door deze repository.