# Compilazione di audio.cpp su Orange Pi 5 Plus (RK3588) Guida alla compilazione nativa su Armbian/Debian, con configurazioni separate per CPU, Vulkan e RKNN. ## 1. Ambiente di riferimento - Scheda: Orange Pi 5 Plus - SoC: Rockchip RK3588 - Architettura: ARM64 (`aarch64`) - Sistema: Armbian 25.11 / Debian 13 Trixie - Kernel: `6.1.115-vendor-rk35xx` - GCC: 14.2 - CMake: 3.31.6 - Generatore: Unix Makefiles - Build type: Release - Runtime RKNN: 2.3.2 - Driver NPU: 0.9.8 Non aggiornare kernel, driver NPU o runtime RKNN senza aver prima verificato la compatibilità. ## 2. Controllo dei prerequisiti Verificare gli strumenti di compilazione: gcc --version g++ --version cmake --version gmake --version uname -m L'architettura attesa è aarch64. Verificare la libreria e gli header RKNN: ls -l /usr/lib/librknnrt.so ls -l /home/nvme/epub-gec-experiment/rknn-toolkit2-v2.3.2/rknpu2/runtime/Linux/librknn_api/include/rknn_api.h Verificare i dispositivi grafici: ls -l /dev/dri/ Sull'ambiente di riferimento è presente renderD129. ## 3. Directory di compilazione Il repository si trova in: /home/nvme/audio-cpp-originale Usare una directory distinta per ogni configurazione: - build-orangepi-cpu - build-orangepi-rknn - build-orangepi-vulkan-rknn Non riutilizzare la stessa directory passando da una configurazione all'altra: CMake conserva le opzioni nella cache. ## 4. Compilazione CPU + RKNN Questa configurazione abilita RKNN, CPU nativa, OpenMP e llamafile, senza Vulkan. Configurazione: cmake -S . -B build-orangepi-rknn -DCMAKE_BUILD_TYPE=Release -DENGINE_ENABLE_NATIVE_CPU=ON -DENGINE_ENABLE_OPENMP=ON -DENGINE_ENABLE_LLAMAFILE=ON -DENGINE_ENABLE_RKNN=ON -DENGINE_ENABLE_VULKAN=OFF -DENGINE_RKNN_INCLUDE_DIR=/home/nvme/epub-gec-experiment/rknn-toolkit2-v2.3.2/rknpu2/runtime/Linux/librknn_api/include -DENGINE_RKNN_LIBRARY=/usr/lib/librknnrt.so Compilazione della CLI: cmake --build build-orangepi-rknn --parallel 4 --target audiocpp_cli Per compilare anche il server: cmake --build build-orangepi-rknn --parallel 4 --target audiocpp_server Verifica: build-orangepi-rknn/bin/audiocpp_cli --help ## 5. Compilazione Vulkan + RKNN Questa configurazione abilita contemporaneamente Vulkan e RKNN. Configurazione: cmake -S . -B build-orangepi-vulkan-rknn -DCMAKE_BUILD_TYPE=Release -DENGINE_ENABLE_NATIVE_CPU=ON -DENGINE_ENABLE_OPENMP=ON -DENGINE_ENABLE_LLAMAFILE=ON -DENGINE_ENABLE_RKNN=ON -DENGINE_ENABLE_VULKAN=ON -DENGINE_RKNN_INCLUDE_DIR=/home/nvme/epub-gec-experiment/rknn-toolkit2-v2.3.2/rknpu2/runtime/Linux/librknn_api/include -DENGINE_RKNN_LIBRARY=/usr/lib/librknnrt.so Compilazione della CLI: cmake --build build-orangepi-vulkan-rknn --parallel 4 --target audiocpp_cli Verifica dei dispositivi: build-orangepi-vulkan-rknn/bin/audiocpp_cli --list-devices Sull'ambiente di riferimento il dispositivo Vulkan è il Mali-G610. ## 6. Compilazione CPU-only Questa configurazione non richiede RKNN e non abilita Vulkan. cmake -S . -B build-orangepi-cpu -DCMAKE_BUILD_TYPE=Release -DENGINE_ENABLE_NATIVE_CPU=ON -DENGINE_ENABLE_OPENMP=ON -DENGINE_ENABLE_LLAMAFILE=ON -DENGINE_ENABLE_RKNN=OFF -DENGINE_ENABLE_VULKAN=OFF Compilazione della CLI: cmake --build build-orangepi-cpu --parallel 4 --target audiocpp_cli Se si verificano problemi con le istruzioni CPU native, si può provare una build portabile: cmake -S . -B build-orangepi-cpu-portable -DCMAKE_BUILD_TYPE=Release -DENGINE_ENABLE_NATIVE_CPU=OFF -DENGINE_ENABLE_OPENMP=ON -DENGINE_ENABLE_LLAMAFILE=ON -DENGINE_ENABLE_RKNN=OFF -DENGINE_ENABLE_VULKAN=OFF ## 7. Verifica delle opzioni CMake Per controllare le opzioni della build RKNN: grep -E "^(CMAKE_BUILD_TYPE:|ENGINE_ENABLE_RKNN:|ENGINE_ENABLE_VULKAN:|ENGINE_ENABLE_OPENMP:|ENGINE_ENABLE_NATIVE_CPU:|ENGINE_ENABLE_LLAMAFILE:|ENGINE_RKNN_INCLUDE_DIR:|ENGINE_RKNN_LIBRARY:)" build-orangepi-rknn/CMakeCache.txt Per la build Vulkan, sostituire build-orangepi-rknn con build-orangepi-vulkan-rknn. Dopo aver modificato le opzioni, rieseguire cmake e poi la compilazione. ## 8. Pulizia di una singola build Per ricreare una configurazione da zero, eliminare esclusivamente la relativa directory di build. Esempio per la configurazione RKNN: rm -rf build-orangepi-rknn Dopo la rimozione, ripetere i comandi di configurazione e compilazione. Non eliminare le altre directory di build. ## 9. Note sul backend RKNN L’opzione ENGINE_ENABLE_RKNN=ON abilita il supporto al codice RKNN integrato nel progetto, ma non converte automaticamente i modelli e non trasferisce tutti i calcoli sulla NPU. L’accelerazione NPU è disponibile soltanto per gli stadi che dispongono di un’integrazione RKNN specifica e di modelli compatibili con il SoC RK3588. I modelli RKNN devono essere preparati separatamente e caricati dal runtime secondo il percorso previsto dal modello. Alcuni stadi possono continuare a essere eseguiti sulla CPU o sulla GPU Vulkan. La presenza di RKNN nella configurazione non garantisce quindi un miglioramento delle prestazioni. ## 10. Verifica delle prestazioni Confrontare sempre le diverse configurazioni usando lo stesso modello, gli stessi input e le stesse condizioni di test. Per CosyVoice 3, nelle prove effettuate, l’esecuzione CPU-only del Flow è risultata più veloce rispetto all’integrazione RKNN con una configurazione fissa di 500 frame, quando l’input richiedeva 402 frame. Questo risultato riguarda quella specifica prova e non deve essere generalizzato a tutti i modelli o a tutti gli stadi. Quando possibile, misurare separatamente i tempi di LLM, Flow e HiFT. Mantenere la configurazione CPU-only come riferimento per valutare il vantaggio reale di Vulkan e RKNN. ## 11. Documentazione di riferimento Per ulteriori dettagli consultare: - docs/build/rockchip-npu.md: integrazione e compilazione per NPU Rockchip. - README.md: panoramica generale del progetto. - CMD.md: comandi e procedure di lavoro personali. - README_fabio.md: note e configurazioni specifiche. Questa guida descrive l’ambiente Orange Pi 5 Plus RK3588 verificato. Per altre schede o versioni di sistema, controllare prima la compatibilità delle librerie e dei driver.