QualcommWireless/docs/BLUETOOTH.md

Diagnostic & Architecture Bluetooth (Qualcomm WCN7850)

Ce document décrit en profondeur le fonctionnement du sous-système Bluetooth de la puce Qualcomm FastConnect 7800 (WCN7850), l'analyse détaillée du crash au démarrage de session macOS, et la solution définitive.

---

1. Description du Contrôleur Bluetooth

• Identifiants matériels :
  • Vendeur : 0x0489 (Foxconn / Hon Hai)
  • Produit : 0xe10d
  • Nom du chipset : Qualcomm WCN7850 Bluetooth 5.4 HCI
  • Bus : USB 2.0 (Interface 0 : Contrôle/Bulk HCI, Interface 1 : SCO Audio)
• Rôle dans macOS :
  • Fournit la couche transport HCI (Host Controller Interface) au daemon système bluetoothd.
  • Gère les périphériques HID (claviers, souris, Magic Trackpad), les casques audio A2DP/HFP, et les fonctionnalités Continuity / AirDrop si la carte Wi-Fi est associée.

---

2. Analyse Post-Mortem du Kernel Panic au Login

2.1. Symptômes observés

• Au démarrage, l'écran de verrouillage macOS s'affiche correctement.
• Dès que le mot de passe utilisateur est validé et que la session commence à charger, l'écran se fige complètement puis la machine redémarre (Kernel Panic).

2.2. Traces du Kernel Panic (Kernel-2026-10-15-174229.panic)

panic(cpu 0 caller 0xffffff800ec4b86d): A kext releasing a(n) IOBluetoothL2CAPChannel has corrupted the registry. @OSObject.cpp:224
Panicked task 0xffffff8b71de3980: 235 threads: pid 0: kernel_task
Backtrace (CPU 0), panicked thread: 0xffffff903e00ab30, Frame : Return Address
0xfffffff2a9823bd0 : 0xffffff800edd07bd mach_kernel : _panic + 0x81
0xfffffff2a9823cc0 : 0xffffff800ec4b86d mach_kernel : __ZNK8OSObject13taggedReleaseEPKvi + 0x8d
0xfffffff2a9823cd0 : 0xffffff8010694464 com.apple.iokit.IOBluetoothFamily : __ZN17IOBluetoothDevice13removeChannelEP23IOBluetoothL2CAPChannel + 0xae
0xfffffff2a9823d70 : 0xffffff8010697629 com.apple.iokit.IOBluetoothFamily : __ZN23IOBluetoothL2CAPChannel6stopWLEv + 0x65
0xfffffff2a9823df0 : 0xffffff8010697583 com.apple.iokit.IOBluetoothFamily : __ZN23IOBluetoothL2CAPChannel4stopEP9IOService + 0x33
0xfffffff2a9823e90 : 0xffffff800ecc7dd6 mach_kernel : __ZN9IOService15terminateWorkerEj + 0x8b6
Kernel Extensions in backtrace:
   com.apple.iokit.IOBluetoothFamily(9.0)

2.3. Cause Racine (Root Cause)

1. L'Intrusion de IntelBTPatcher.kext :
   • Le kext tiers IntelBTPatcher.kext (conçu spécifiquement pour les puces Intel AX200/AX210) était resté activé (Enabled: true) dans le fichier config.plist d'OpenCore.
   • IntelBTPatcher intercepte et patche globalement les méthodes virtuelles de IOBluetoothFamily dans le noyau pour contourner des anomalies de paquets HCI propres à Intel.
2. Incompatibilité avec Darwin 24 (macOS 15 Sequoia) :
   • Sous macOS 15 Sequoia, Apple a profondément remanié la gestion mémoire d'IOKit, notamment la validation des taggedRelease dans OSObject.cpp:224.
   • IntelBTPatcher v2.5.0 (compilé pour Monterey/Ventura/Sonoma) n'est pas compatible avec cette sémantique et effectue une libération désynchronisée (double release ou tag invalide) lors de la fermeture d'un canal L2CAP.
3. Le déclencheur au Login :
   • Dès la validation du mot de passe de session, loginwindow démarre bluetoothd.
   • Les périphériques Apple couplés (notamment la Magic Mouse 2 78:CA:39:F4:15:5A et le Magic Keyboard 78:CA:39:4C:A3:9A) établissent ou réinitialisent leurs canaux L2CAP (HID ACL).
   • Lors de la libération ou du renouvellement du canal L2CAP (IOBluetoothDevice::removeChannel), le hook corrompu d'IntelBTPatcher déclenche immédiatement l'assertion de corruption de registre du noyau (OSObject::taggedRelease), provoquant le kernel panic instantané.

---

3. Solution et Bonnes Pratiques

3.1. Désactivation définitive d'IntelBTPatcher

Pour les cartes Qualcomm FastConnect 7800, IntelBTPatcher ne doit JAMAIS être utilisé :

• Dans /Volumes/EFI/EFI/OC/config.plist :

  <dict>
      <key>BundlePath</key>
      <string>IntelBTPatcher.kext</string>
      <key>Enabled</key>
      <false/>
  </dict>
  

• Suppression physique du bundle IntelBTPatcher.kext du dossier EFI/OC/Kexts/.

3.2. Rôle de BlueToolFixup.kext

• BlueToolFixup.kext (de la suite BrcmPatchRAM / Acidanthera) est, quant à lui, requis et compatible.
• Il patche dynamiquement bluetoothd en espace utilisateur pour accepter les dongles tiers non-Apple et débloquer les commandes de bas niveau (HCI Vendor Commands).
• Arguments de démarrage recommandés dans boot-args : -btlfxallowanyaddr -btlfxnvramcheck

---

4. Séquence de Chargement du Firmware USB

Le firmware Bluetooth Qualcomm nécessite deux étages binaires téléversés au démarrage :

sequenceDiagram
    autonumber
    participant K as QualcommWireless (Kext)
    participant USB as Contrôleur USB WCN7850
    participant D as bluetoothd (macOS)

    K->>USB: QCA_GET_TARGET_VERSION (Requête de contrôle vendeur)
    USB-->>K: Versions ROM / Patch / RAM
    K->>USB: QCA_CHECK_STATUS (Vérification statut)
    USB-->>K: Status 0x00 (RAMPATCH et Syscfg requis)
    K->>USB: EP0: Header DFU (40 octets)
    K->>USB: EP2 (Bulk OUT): RAMPATCH WCN7850 (paquets de 4096 octets)
    K->>USB: EP0: Header DFU (4 octets)
    K->>USB: EP2 (Bulk OUT): NVM WCN7850 (paquets de 4096 octets)
    K->>USB: HCI Reset (0x03, 0x0C, 0x00)
    USB-->>K: HCI Command Complete Event
    K->>K: Injection des propriétés IORegistry (spoofing CSR 0x0a12)
    K->>K: Libération de l'interface USB (close)
    Note over D,USB: bluetoothd prend la main en exclusivité
    D->>USB: Établissement transport HCI USB
    D->>USB: Connexion Magic Mouse 2 / Clavier (L2CAP)

Grâce à cette séquence, le contrôleur Bluetooth WCN7850 opère de manière parfaitement stable sous macOS Sequoia sans aucun crash au démarrage de session.