fix(rknpu2): improve NPU stability with error propagation and IOVA fragmentation fixes

[KHAEntertainment]

Summary

Implements TraycerAI's suggested improvements from issue #2 plus an IOVA fragmentation fix for large models (>9B parameters) on RK3588.

Changes

Error Handling Improvements:

• rknn_matmul_run error propagation - errors now properly fail instead of silently continuing
• Memory context failure logging - NPU backend will log clear errors when initialization fails
• B-matrix memcpy guard assertion - prevents buffer overflow in debug builds

Environment Variables:

• RKNN_DEVICE - Select device (e.g., "RK3588")
• RKNN_CORE_MASK - NPU core affinity ("0", "1", "2", "auto")
• RKNN_SPLIT_FACTOR - Split B-matrix into smaller segments to reduce IOVA allocation size

IOVA Fragmentation Fix:
The RK3588 NPU uses IOMMU for address translation. Large models like Qwen 9B require ~11-17MB contiguous IOVA allocations which fail when other peripherals (RGA, VPU, JPEG) have fragmented the address space.

RKNN_SPLIT_FACTOR=N splits each core's segments into N pieces, reducing the max contiguous allocation by Nx while maintaining parallelization via round-robin core assignment.

Test Commands

# Test with split factor for large models
RKNN_SPLIT_FACTOR=4 ./build/bin/llama-cli -m Qwen3.5-9B-Q8_0.gguf -p 'Hello' -n 64

# Use specific NPU core
RKNN_CORE_MASK=1 ./build/bin/llama-cli -m model.gguf

Commits

• 36132380a fix(rknpu2): implement TraycerAI suggested improvements
• bf93a5b01 fix(rknpu2): add RKNN_SPLIT_FACTOR to reduce IOVA allocation size
• 7c8e767d6 docs: document RKNN environment variables and IOVA exhaustion fix

Test plan

• Rebuild on Rock 5C: cmake --build build
• Test Qwen 9B with RKNN_SPLIT_FACTOR=4
• Verify no IOVA errors in dmesg
• Test RKNN_CORE_MASK=1 for single-core execution

🤖 Generated with Claude Code

[coderabbitai]

Warning

Rate limit exceeded

@KHAEntertainment has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 1 minutes and 9 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3eca7cf1-730f-4424-99f7-30350ffb2c2b

📥 Commits

Reviewing files that changed from the base of the PR and between 2806dc3 and 7c8e767.

📒 Files selected for processing (4)

• README.md
• docs/IOVA_EXHAUSTION.md
• ggml/src/ggml-rknpu2/README.md
• ggml/src/ggml-rknpu2/ggml-rknpu2.cpp

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch qwen3-support

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}