De Rockchip RKNN NPU-softwarestack begrijpen

Na het starten van een RK3588-bord met een 6-TOPS-NPU voer je een YOLO-voorbeeld uit. Dit verschijnt:

rknpu driver version is too low
failed to initialize rknn runtime
invalid rknn model
unsupported target platform
failed to submit task

Wat is er gebeurd?

Dit komt vaak voor bij een eerste AI-implementatie op een gespecialiseerd edgeplatform. Waarom werkt pc-software niet op het bord? Waarom slaagt de conversie, maar mislukt de uitvoering? Waarom werkt hetzelfde model slechts op één bord?

Dit artikel legt het gebruik van de Rockchip-NPU helder en grondig uit.

Het beantwoordt deze kernvragen:

• Wat zijn RKNN-Toolkit2, RKNN Runtime en het RKNPU-stuurprogramma?
• Waarom is een nieuw librknnrt.so soms onvoldoende?
• Waarom mag rknpu.ko niet zomaar worden vervangen?
• Hoe verschillen CNN-, Transformer- en LLM-routes?
• Zit de fout in model, Runtime, driver of systeemimage?
• Wanneer moet je geen NPU gebruiken?

1. Overzicht: RK NPU is geen enkel pakket

Tussen PyTorch en NPU-uitvoering zitten minstens de conversietool, het modelbestand, de Runtime op het bord, de Linux-driver en NPU-hardware.

Deze keten heeft twee fasen.

Modelvoorbereiding op de pc:

PyTorch / TensorFlow
        ↓
       ONNX
        ↓
RKNN-Toolkit2
        ↓
.rknn-model gecompileerd voor RK3588 of RK3576

Modeluitvoering op het bord:

Toepassing
   ↓
RKNNLite / RKNN C API
   ↓
librknnrt.so
   ↓
Linux-systeemaanroepen
   ↓
RKNPU-kernelstuurprogramma
   ↓
NPU-hardware

Elk onderdeel heeft een eigen taak:

Zie de officiële RKNN-Toolkit2-repository.

Bepaal bij problemen eerst welke laag faalt.

2. Een .rknn-model genereren

De NPU voert PyTorch of doorgaans ONNX niet rechtstreeks uit. ONNX wisselt grafen uit; .rknn is door Rockchip geoptimaliseerd en gecompileerd.

Minimale ONNX-conversie:

from rknn.api import RKNN

rknn = RKNN(verbose=True)

rknn.config(
    target_platform="rk3576",
    mean_values=[[0, 0, 0]],
    std_values=[[255, 255, 255]],
)

rknn.load_onnx(model="model.onnx")
rknn.build(do_quantization=False)
rknn.export_rknn("model_rk3576.rknn")
rknn.release()

target_platform bindt het model aan een chip. Een RK3588-model werkt niet automatisch op RK3576 of RK3568.

RKNN-Toolkit2 doet daarnaast:

• Grafiek- en Tensor-Shape-analyse;
• Constant folding en verwijdering van overbodige nodes;
• Operatorfusie voor de NPU;
• NCHW/NHWC-conversie;
• Controle van operators, typen en Shapes;
• FP16-, INT8- of andere kwantisatie;
• Generatie van uitvoeringsgraaf en gewichten.

Werking in ONNX Runtime garandeert geen RKNN-conversie of laden op het bord.

Laden hangt ook af van Runtime, driver, geheugen en chip.

3. Wat is de Runtime?

Op RK3588/RK3576 Linux is de kern meestal:

librknnrt.so

Dit is een gedeelde userspacebibliotheek, geen kerneldriver of volledige omgeving.

Python-aanroeppad:

Python-toepassing
   ↓
RKNNLite
   ↓
librknnrt.so
   ↓
RKNPU-stuurprogramma

C/C++-aanroeppad:

C/C++-toepassing
   ↓
RKNN C API
   ↓
librknnrt.so
   ↓
RKNPU-stuurprogramma

Minimaal Python-voorbeeld:

from rknnlite.api import RKNNLite

runtime = RKNNLite()

ret = runtime.load_rknn("model_rk3576.rknn")
if ret != 0:
    raise RuntimeError("load_rknn failed")

ret = runtime.init_runtime(core_mask=RKNNLite.NPU_CORE_0_1)
if ret != 0:
    raise RuntimeError("init_runtime failed")

outputs = runtime.inference(inputs=[input_tensor])
runtime.release()

init_runtime() maakt een inferentiecontext en kan:

1. Chip en driver controleren;
2. Het RKNN-model parseren;
3. Compatibiliteit controleren;
4. NPU-kernen kiezen;
5. Geheugen voor gewichten en Tensors voorbereiden;
6. Driverresources maken.

De Runtime vertaalt en plant; de driver bestuurt de NPU.

Is rknn_server vereist?

Nee. Het verbindt pc en bord via USB/ADB voor debugging, analyse en inferentie op afstand.

Lokale apps roepen meestal direct librknnrt.so aan.

4. Plaats van de RKNPU-driver in Linux

Alleen de kerneldriver mag NPU-registers, interrupts en fysiek geheugen beheren.

Gebruikersruimte: Toepassing → RKNNLite / RKNN API → librknnrt.so
                         │
                    Grens van systeemaanroepen
                         │
Kernelruimte:         RKNPU-stuurprogramma
                         │
Hardware:             NPU

De driver verzorgt:

• NPU-initialisatie;
• Klokken, energiedomeinen en reset;
• NPU-geheugen;
• Runtime-taken;
• Planning van NPU-kernen;
• Interrupts en voltooiingsmeldingen;
• IOMMU-adresmapping;
• Versie- en capaciteitsinformatie.

Wat zijn ioctl en mmap?

Runtime en driver communiceren via ioctl, mmap, poll en DMA.

• ioctl stuurt apparaatspecifieke opdrachten;
• mmap koppelt driverbuffers aan de procesruimte;
• DMA laat de NPU geheugen benaderen zonder bytekopieën door de CPU;
• poll wacht op voltooiing.

Eenvoudig gezegd:

mmap: bepaalt waar gegevens worden geplaatst en hoe beide kanten ze benaderen
ioctl: vertelt het apparaat welke bewerking het moet uitvoeren

librknnrt.so omvat synchronisatie, taakindiening en wachten.

Net als netwerk of USB bereikt RKNN hardware via Runtime en driver.

5. Waarom versiecompatibiliteit belangrijk is

Een implementatie omvat meerdere versies:

RKNN-Toolkit2-versie
        ↓
.rknn-modelindeling en doelchip
        ↓
RKNN-Toolkit-Lite2- / librknnrt.so-versie
        ↓
Versie van het RKNPU-stuurprogramma
        ↓
Linux-kernel en BSP

Ook rknn_server, headers en bibliotheken moeten bij dezelfde SDK horen.

Typische conflicten:

• Nieuw Toolkit-model, te oude Runtime;
• Nieuw librknnrt.so, te oude driver;
• Nieuw Python-pakket laadt oude Runtime;
• Server en Runtime uit andere releases;
• RK3588-model op RK3576;
• Nieuwe container-Runtime, oude hostdriver.

Gebruik de officiële borddocumentatie; verouderde informatie veroorzaakt dergelijke conflicten.

reComputer AI Lab bundelt actuele RK3588/RK3576-bronnen. Het biedt CV-, LLM- en VLM-implementaties, tools en open praktijkprojecten.

Voor producten geldt niet “alles nieuw”, maar:

Gebruik een gevalideerde combinatie van Toolkit, model, Runtime, Server en driver.

6. Ontstaan van rknpu driver version is too low

Vervang rknpu.ko niet meteen; bepaal eerst de oorzaak.

librknnrt.so vraagt driverversie en functies op. Ontbreken vereisten, dan verschijnt:

rknpu driver version is too low

Dit gebeurt vaak wanneer op een ouder bord alleen de Runtime is bijgewerkt, niet image en wiki. Gebrekkige documentatie veroorzaakt later problemen; kies niet alleen op prijs.

Meestal is dit een Runtime-driverconflict, geen beschadigd bestand.

Veelvoorkomende oorzaken:

1. Alleen librknnrt.so bijgewerkt;
2. Verkeerde van meerdere kopieën geladen;
3. Nieuwe module staat alleen op schijf;
4. Driver is in de kernel ingebouwd;
5. vermagic, symbolen of configuratie verschillen;
6. Nieuwe container, oude hostdriver;
7. BSP en Runtime horen niet bij elkaar.

Verzamel eerst:

# De kernelversie controleren
uname -a

# Initialisatie en fouten van het RKNPU-stuurprogramma controleren
dmesg | grep -i rknpu

# Als het stuurprogramma als module is geladen, de huidige modules weergeven
lsmod | grep rknpu

# De module op schijf controleren; pas het pad aan het werkelijke systeem aan
modinfo rknpu

# Alle Runtime-kopieën op het systeem zoeken
find / -name 'librknnrt.so*' 2>/dev/null

# Controleren welke gedeelde bibliotheken aan de toepassing zijn gekoppeld
ldd ./your_application

Controleer bij een actief proces ook:

grep librknnrt /proc/$(pidof your_application)/maps

Zo zie je welk librknnrt.so werkelijk is geladen.

Aanbevolen volgorde:

De huidige kernel- en stuurprogrammaversies bevestigen
        ↓
De Runtime bevestigen die daadwerkelijk door de toepassing is geladen
        ↓
De doelchip van het model en de versie van het conversieprogramma bevestigen
        ↓
Een compatibele SDK of systeemimage van de bordfabrikant zoeken
        ↓
Indien nodig de volledige BSP upgraden of het stuurprogramma opnieuw compileren met de huidige kernelbroncode

7. Waarom rknpu.ko niet zomaar vervangen?

.ko is een kernelmodule en moet exact bij de actieve kernel passen.

Controleer eerst de bouwwijze:

CONFIG_ROCKCHIP_RKNPU=y   Stuurprogramma ingebouwd in de kernel
CONFIG_ROCKCHIP_RKNPU=m   Stuurprogramma gecompileerd als afzonderlijke module

Bij een ingebouwde driver helpt kopiëren niet; update kernel of volledige image.

Bij een module moet gelden:

• Passende kernelbron;
• Compatibele configuratie en toolchain;
• Gelijke vermagic;
• Benodigde kernelsymbolen;
• Passende Device Tree, voeding, klok, IOMMU en geheugen;
• Geen proces gebruikt de NPU;
• Ondertekening en secure boot staan laden toe.

Vergelijk kernel en module:

uname -r
modinfo ./rknpu.ko | grep vermagic

Succesvol laden garandeert geen volledig BSP. Prioriteit:

1. Volledig image van de leverancier;
2. Herbouw vanuit passend BSP;
3. Losse module alleen bij volledige overeenkomst;
4. Bewaar een opstartbare back-up.

RKNPU 0.9.8 is pas actief als de actieve kernel de compatibele 0.9.8-driver laadt, niet wanneer alleen een .ko bestaat.

8. Implementatieroutes voor CNN, Transformer en LLM

Deze AI-modellen gebruiken niet noodzakelijk dezelfde route.

CNN: de gebruikelijke RKNN-route

Classificatie, YOLO, segmentatie en pose gebruiken meestal:

PyTorch → ONNX → RKNN-Toolkit2 → .rknn → RKNN Runtime → NPU

Convolutie, activatie en pooling passen goed. Let op:

• Invoerformaat en lay-out;
• RGB/BGR-volgorde;
• mean/std tegenover preprocessing;
• INT8-dataset;
• Head-decoding en NMS;
• Kopieën tussen camera, RGA en NPU.

Transformer: operators en dynamische Shapes

Let bij RKNN-Toolkit2 op:

• MatMul；
• Softmax；
• LayerNorm/RMSNorm;
• reshape/transpose;
• Dynamische sequentielengte;
• Tensor-geheugen;
• CPU-/GPU-hulpoperators.

De naam Transformer garandeert geen volledige NPU-uitvoering; operators, Shapes en typen zijn bepalend.

LLM: meestal RKLLM

LLM’s gebruiken KV Cache, Prefill, token-Decode, lange context en sampling; zie RKNN-LLM:

Hugging Face-model
        ↓
Conversie en kwantisatie met RKLLM-Toolkit
        ↓
.rkllm-model
        ↓
RKLLM Runtime
        ↓
RKNPU-stuurprogramma en NPU

RKLLM gebruikt RKNPU, maar verschilt in model, API en uitvoering. Controleer de officiële lijst.

9. Twee routes voor grote modellen op RK3588

Er zijn twee gebruikelijke routes.

Route 1: GGUF + llama.cpp + CPU

Eenvoudig, veel modellen en goed te debuggen; vermijdt RKNN-conversie en driverconflicten.

Geschikt voor:

• Snelle validatie;
• Vaak wisselen;
• Maximale compatibiliteit;
• Teams zonder NPU-ervaring;
• Niet-ondersteunde RKLLM-modellen.

Nadelen zijn meer CPU-gebruik, energie en mogelijk lagere tokensnelheid.

Route 2: RKLLM + NPU

Meer throughput, maar meer engineering:

• Architectuur controleren;
• Met voorgeschreven toolchain converteren;
• Runtime en driver afstemmen;
• Kwantisatienauwkeurigheid testen;
• Gewichten, KV Cache en geheugen plannen;
• Prefill en Decode onderscheiden;
• Contextlengtes testen.

De NPU voert GGUF niet rechtstreeks uit, maar gebruikt een eigen formaat en Runtime.

Keuzehulp:

Meet end-to-end, niet alleen TOPS; geheugen, bandbreedte, KV Cache en CPU beïnvloeden LLM’s.

10. Gelaagde probleemoplossing

Bepaal eerst in welke laag de fout zit.

Laag 1: conversie

Typische symptomen:

unsupported operator
shape inference failed
build model failed

Controleer ONNX, Opset, Shape, dynamiek, operators, logs en kalibratiedata.

Laag 2: laden

Typische symptomen:

invalid rknn model
unsupported target platform
load_rknn failed

Controleer Toolkit, target_platform, Runtime-ondersteuning en bestandsintegriteit.

Laag 3: Runtime-initialisatie

Typische symptomen:

failed to initialize rknn runtime
driver version is too low
cannot open shared object file
undefined symbol

Controleer bibliotheekpad, architectuur, 32/64-bit, Runtime, driver en device nodes.

Laag 4: uitvoering

Typische symptomen:

failed to submit task
IOMMU fault
allocate memory failed

Controleer dmesg, geheugen, CMA/DMA, IOMMU, Tensors en paralleliteit.

Laag 5: prestaties

rknn_run() omvat vaak niet:

• Afbeelding lezen en decoderen;
• resize, letterbox en kleurconversie;
• CPU-NPU-kopieën;
• Decoding en NMS;
• Onnodig wachten;
• NPU-kernkeuze;
• Klokverlaging;
• Thermal throttling;
• Slecht threadontwerp.

Meet minstens afzonderlijk:

Tijd voor het inlezen van invoer
Voorverwerkingstijd
Zuivere modelinferentietijd
Nabewerkingstijd
Totale end-to-endtijd

Alleen NPU-tijd vertegenwoordigt de echte appprestaties niet.

11. Gegevens vóór een supportvraag

Volledige informatie is belangrijker dan één foutmelding:

SoC-model:
Model van het ontwikkelbord:
Besturingssysteem en bron van de image:
Linux-kernelversie:
Versie van het RKNPU-stuurprogramma:
RKNN-Toolkit2-versie:
RKNN-Toolkit-Lite2-versie:
RKNN Runtime-versie:
rknn_server-versie (indien gebruikt):
Modelbron en ONNX Opset:
Doelplatform:
Gekwantiseerd:
Volledig toepassingslogboek:
Relevant dmesg-logboek:
Kan het officiële voorbeeld worden uitgevoerd:

De officiële test is doorslaggevend:

• Mislukt die ook: systeem, Runtime of driver;
• Lukt die wel: eigen model of I/O;
• C lukt, Python niet: pakket en bibliotheekpad;
• Host lukt, container niet: mapping, rechten en Runtime.

12. Veelvoorkomende misverstanden

Onthoud:

• Een NPU voert niet elk netwerk uit;
• ONNX-succes garandeert RKNN niet;
• RKNN-conversie garandeert bordcompatibiliteit niet;
• librknnrt.so werkt de kerneldriver niet bij;
• Kopiëren van rknpu.ko laadt hem niet;
• Een nieuwe driver past niet altijd bij kernel/BSP;
• Pre- en postprocessing draaien niet automatisch op NPU;
• Meer kernen schalen één model niet automatisch;
• Containers vervangen de hostdriver niet;
• NPU-tijd is geen end-to-endtijd;
• Gelijke TOPS betekenen geen gelijke praktijkprestaties.