# Guide Root - OnePlus Pad 3 (OPD2415) pour le projet Kazeia

## Pourquoi rooter ?

Le Snapdragon 8 Elite embarque un NPU (Neural Processing Unit) capable d'exécuter les modèles d'IA 10 à 100x plus vite que le CPU. Sans root, Android bloque l'accès aux librairies vendor Qualcomm (libcdsprpc.so, libQnnHtp.so) nécessaires pour communiquer avec le NPU depuis une application tierce.

### Impact sur les performances

| Composant | Sans root (CPU) | Avec root (NPU) | Gain |
|-----------|-----------------|------------------|------|
| **STT Whisper-Base** | ~1500ms | ~50ms | x30 |
| **LLM Qwen3-4B (Genie SDK)** | Indisponible (erreur -5) | ~30 tok/s | ∞ |
| **TTS Chatterbox** | OOM crash (1.4 GB RAM) | ~1-3s sur NPU | Fonctionne |
| **Monitoring GPU/NPU** | 0% (sysfs inaccessible) | Métriques temps réel | Visibilité |
| **Pipeline complet (STT→LLM→TTS)** | Impossible | ~4-8s end-to-end | Pipeline complet |

### Composants bloqués sans root

- **Genie SDK** : le `GenieDialogConfig_createFromJson()` retourne le code d'erreur -7 car il ne peut pas ouvrir les devices DSP
- **QNN HTP** : `libcdsprpc.so` nécessite `libhidlbase.so` du namespace vendor, inaccessible aux apps normales
- **ONNX Runtime QNN EP** : le QNN Execution Provider s'initialise mais ne peut pas communiquer avec le HTP
- **Sysfs monitoring** : `/sys/class/kgsl/` (GPU) et `/sys/class/devfreq/` (NPU) sont protégés par SELinux

### Ce qui fonctionne sans root

- Whisper.cpp sur CPU (STT)
- Android TTS natif (Google)
- ONNX Runtime sur CPU
- Silero VAD (ONNX CPU)
- LiteRT avec NNAPI (délégation partielle, limitée)

---

## Prérequis

- **Tablette** : OnePlus Pad 3 (OPD2415)
- **Firmware** : OPD2415_16.0.3.500(EX01) — OxygenOS 16 / Android 16 (API 36)
- **SoC** : Snapdragon 8 Elite (SM8750, plateforme "sun")
- **Slot actif** : A
- **Bootloader** : verrouillé (à déverrouiller)
- **PC** : avec ADB et Fastboot installés
- **Sauvegarde** : aucune donnée critique sur la tablette (le déverrouillage efface tout)

---

## Étape 1 — Activer le déverrouillage OEM

Sur la tablette :

1. **Paramètres → À propos de la tablette**
2. Taper **7 fois** sur "Numéro de build" pour activer les Options développeur
3. **Paramètres → Système → Options développeur**
4. Activer **Déverrouillage OEM**
5. Vérifier que **Débogage USB** est activé

Vérification depuis le PC :

```bash
adb shell getprop sys.oem_unlock_allowed
# Doit retourner "1"
```

---

## Étape 2 — Déverrouiller le bootloader

⚠️ **ATTENTION : Cette étape efface TOUTES les données de la tablette.**

```bash
# Redémarrer en mode fastboot
adb reboot bootloader

# Attendre que la tablette soit en mode fastboot (écran avec logo)
# Vérifier la connexion
fastboot devices

# Déverrouiller le bootloader
fastboot flashing unlock
```

Sur la tablette :
- Utiliser les **boutons volume** pour sélectionner "Unlock the bootloader"
- Confirmer avec le **bouton power**
- La tablette va se réinitialiser et redémarrer

```bash
# Vérification
adb shell getprop ro.boot.vbmeta.device_state
# Doit retourner "unlocked"
```

Après le redémarrage :
- Reconfigurer la tablette (setup minimal)
- Réactiver les Options développeur + Débogage USB

---

## Étape 3 — Récupérer le firmware stock

Il faut le fichier `init_boot.img` de la **même version** de firmware installée.

### Option A : Extraire depuis un OTA complet

1. Télécharger le firmware OPD2415_16.0.3.500 depuis :
   - [OnePlus Firmware Archive](https://www.oneplus.com/support/softwareupgrade)
   - Ou communautés XDA/OnePlus
2. Extraire le ZIP
3. Trouver `init_boot.img` dans le payload :
   ```bash
   # Si le firmware est un payload.bin
   python3 payload_dumper.py payload.bin --out extracted/
   # init_boot.img sera dans extracted/
   ```

### Option B : Extraire depuis la partition active

```bash
# Identifier la partition init_boot
adb shell ls -la /dev/block/by-name/init_boot*

# Extraire (nécessite un accès shell suffisant)
adb shell dd if=/dev/block/by-name/init_boot_a of=/data/local/tmp/init_boot.img
adb pull /data/local/tmp/init_boot.img
```

---

## Étape 4 — Patcher avec Magisk

1. **Télécharger Magisk** : [github.com/topjohnwu/Magisk/releases](https://github.com/topjohnwu/Magisk/releases)
   - Prendre le fichier `Magisk-v28.x.apk` (dernière version stable)

2. **Installer Magisk sur la tablette** :
   ```bash
   adb install Magisk-v28.x.apk
   ```

3. **Transférer init_boot.img sur la tablette** :
   ```bash
   adb push init_boot.img /data/local/tmp/
   ```

4. **Patcher avec Magisk** :
   - Ouvrir l'app Magisk sur la tablette
   - Appuyer sur **"Installer"** à côté de "Magisk"
   - Choisir **"Sélectionner et patcher un fichier"**
   - Naviguer vers `/data/local/tmp/init_boot.img`
   - Attendre la fin du patching
   - Le fichier patché sera dans `/storage/emulated/0/Download/magisk_patched-xxxxx.img`

5. **Récupérer l'image patchée** :
   ```bash
   adb pull /storage/emulated/0/Download/magisk_patched-28100_xxxxx.img
   ```

---

## Étape 5 — Flasher l'image patchée

```bash
# Redémarrer en fastboot
adb reboot bootloader

# Flasher l'image patchée sur la partition init_boot
fastboot flash init_boot magisk_patched-28100_xxxxx.img

# Redémarrer
fastboot reboot
```

---

## Étape 6 — Vérification

Après le redémarrage :

```bash
# Vérifier que Magisk est actif
adb shell su -c id
# Doit retourner: uid=0(root) gid=0(root)

# Vérifier l'accès aux libs vendor
adb shell su -c "ls /vendor/lib64/libcdsprpc.so"
adb shell su -c "ls /vendor/lib64/libQnnHtp.so"

# Vérifier l'accès au DSP
adb shell su -c "ls /dev/adsprpc-smd"

# Vérifier les sysfs GPU
adb shell su -c "cat /sys/class/kgsl/kgsl-3d0/gpubusy"
```

---

## Étape 7 — Configuration post-root pour Kazeia

### Permissions DSP pour l'app

```bash
# Donner accès au DSP à l'app Kazeia
adb shell su -c "chmod 666 /dev/adsprpc-smd"
adb shell su -c "chmod 666 /dev/cdsprpc-smd"

# Ou via Magisk module pour persister après reboot
```

### Module Magisk recommandé

Créer un module Magisk qui :
- Rend les libs QNN accessibles aux apps
- Ouvre les permissions DSP au boot
- Expose les sysfs GPU/NPU

### Variables d'environnement

L'app devra setter ces variables avant de charger les libs QNN :
```
ADSP_LIBRARY_PATH=/vendor/lib64/
LD_LIBRARY_PATH=/vendor/lib64/
```

---

## Risques et précautions

### Ce que le root implique

- **Garantie** : techniquement annulée (mais reversible en re-verrouillant le bootloader)
- **Mises à jour OTA** : ne fonctionneront plus automatiquement (flash manuel nécessaire)
- **SafetyNet / Play Integrity** : certaines apps (banque, Netflix) peuvent refuser de fonctionner
  - Solution : module Magisk "Universal SafetyNet Fix" ou "Play Integrity Fix"
- **Sécurité** : le root expose le système — ne pas installer d'apps douteuses

### Comment revenir en arrière

```bash
# Re-verrouiller le bootloader (efface tout)
adb reboot bootloader
fastboot flashing lock
# Confirmer sur la tablette
fastboot reboot
```

### Sauvegarde avant root

```bash
# Sauvegarder les modèles déjà poussés
adb pull /data/local/tmp/kazeia/ ./backup_kazeia/
```

---

## Résumé des commandes

```bash
# 1. Déverrouiller
adb reboot bootloader
fastboot flashing unlock
# Confirmer sur tablette

# 2. Après reconfiguration tablette
adb install Magisk-v28.x.apk
adb push init_boot.img /data/local/tmp/

# 3. Patcher sur tablette via app Magisk, puis récupérer
adb pull /storage/emulated/0/Download/magisk_patched-*.img

# 4. Flasher
adb reboot bootloader
fastboot flash init_boot magisk_patched-*.img
fastboot reboot

# 5. Vérifier
adb shell su -c id
```

---

## Après le root — Impact sur Kazeia

Une fois rooté, modifier `KazeiaApplication.kt` pour ajouter les chemins vendor :

```kotlin
companion object {
    const val MODELS_DIR = "/data/local/tmp/kazeia/models"

    init {
        // Avec root, les libs vendor sont accessibles
        System.setProperty("ADSP_LIBRARY_PATH", "/vendor/lib64/")
    }
}
```

Les composants suivants deviendront fonctionnels :
- ✅ Genie SDK → LLM Qwen3-4B sur NPU
- ✅ ONNX Runtime QNN EP → Whisper encoder/decoder sur NPU
- ✅ Monitoring GPU/NPU via sysfs
- ✅ Chatterbox TTS sur NPU (réduction mémoire)

---

*Document créé le 28 mars 2026 — Projet Kazeia*
*Damien Micottis & Richard Loyer*