premier push

2026-10-15 18:07:10 +02:00
commit b03b6c8197
@@ -0,0 +1,106 @@
+# 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`)
+```text
+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` :
+  ```xml
+  <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 :
+
+```mermaid
+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.