QualcommWireless/README.md

QualcommWireless

Pilote unifié haute performance pour les modules Qualcomm FastConnect 7800 (WCN7850) sous macOS Tahoe (26.x / Darwin 25) et macOS Sequoia (15.x / Darwin 24).

Ce projet fournit une prise en charge Wi-Fi 7 native intégrée à la pile réseau sans fil Apple (IO80211Controller / Skywalk), ainsi que l'initialisation complète et le téléversement de microprogramme du sous-système Bluetooth 5.4 via USB.

---

Sommaire

• Présentation du Matériel
• Fonctionnalités Principales
• Architecture du Pilote
• Documentation Technique
• Compilation
• Installation avec OpenCore
• Résolution des Problèmes & Bonnes Pratiques
• Licence

---

Présentation du Matériel

Le module Qualcomm FastConnect 7800 (WCN7850) combine deux contrôleurs matériels sur une même carte M.2 :

Composant	Interface Bus	Identifiants Matériels (VID:PID)	Spécifications
Wi-Fi	PCI Express Gen3 x1	0x17cb:0x1107	Wi-Fi 7 (802.11be), 2.4/5/6 GHz, 320 MHz, 4096-QAM
Bluetooth	USB 2.0 (Bus Interne)	0x0489:0xe10d (Foxconn)	Bluetooth 5.4, LE Audio, HCI USB Standard

---

Fonctionnalités Principales

🌐 Wi-Fi Natif Apple (QualcommWifi)

• Véritable interface sans fil Apple80211 : Dérive directement de IO80211Controller, compatible avec l'ABI Skywalk de macOS Tahoe 26.x (__IO80211_TARGET=260000, vtable 463 slots), évitant toute émulation Ethernet artificielle.
• Intégration macOS complète :
  • Détection automatique dans le Centre de Contrôle et la barre des menus.
  • Compatibilité avec le framework CoreWLAN et le daemon système airportd.
  • Scan des réseaux environnants (APPLE80211_IOC_SCAN_REQ_MULTIPLE).
  • Prise en charge des canaux 2.4 GHz (1-14), 5 GHz (UNII-1 à UNII-4) et 6 GHz (UNII-5 à UNII-8).
• Moteur MHI / BHI & Fenêtrage PCIe :
  • Implémente le protocole Qualcomm MHI (Modem Host Interface).
  • Gestion automatique du registre de fenêtrage BAR0 (0x310c).
  • Chargement des microprogrammes amss.bin, board-2.bin et m3.bin.

📶 Bluetooth 5.4 LE Audio (QualcommWireless)

• Initialisation & Patching du Firmware USB :
  • Vérification de l'état QCA (QCA_CHECK_STATUS, QCA_GET_TARGET_VERSION).
  • Téléversement séquentiel du RAMPATCH (rampatch_usb_00190200_bin) et du NVM via les pipes de contrôle EP0 et Bulk OUT EP2.
  • Réinitialisation matérielle propre (HCI_Reset) et interception Shadow VTable de IOUSBHostDevice::deviceRequest (slot 374 / 0x176).
• Compatibilité Apple :
  • Connexion fluide des périphériques Apple (Magic Mouse 2, Magic Keyboard, Magic Trackpad).
  • Audio Bluetooth (A2DP, HFP/HSP) et profils GATT/BLE.

---

Architecture du Pilote

graph TD
    subgraph macOS["macOS Tahoe 26.x (Darwin 25) / Sequoia 15.x"]
        UI["Centre de Contrôle / Barre de Menus"]
        AirportD["airportd / CoreWLAN.framework"]
        BtD["bluetoothd / IOBluetoothFamily"]
        IO80211["com.apple.iokit.IO80211Family"]
        IOUSB["com.apple.iokit.IOUSBHostFamily"]
    end

    subgraph Kext["QualcommWireless.kext"]
        QWifi["QualcommWifi (IO80211Controller)\n• handleCardSpecific / Skywalk\n• BHI/MHI Pipeline\n• BAR0 Windowing"]
        QBt["QualcommWireless (IOService)\n• DFU Firmware Upload\n• RAMPATCH + NVM\n• Shadow VTable & Registry Spoofing"]
    end

    subgraph Hardware["Puce Qualcomm WCN7850"]
        PCIe["Bus PCIe (0x17cb:0x1107)\nWi-Fi 7 (AMSS)"]
        USB["Bus USB (0x0489:0xe10d)\nBluetooth 5.4 HCI"]
    end

    UI --> AirportD
    AirportD --> IO80211
    IO80211 --> QWifi
    QWifi --> PCIe

    BtD --> IOUSB
    IOUSB --> QBt
    QBt --> USB

---

Documentation Technique

Le dossier docs/ contient une documentation technique exhaustive :

• 📐 ARCHITECTURE.md : Détail complet des interactions logicielles et matérielles, pipelines firmware et topologies de bus.
• 🔵 BLUETOOTH.md : Analyse post-mortem du crash L2CAP au démarrage de session, séquence DFU et configuration bluetoothd sous Sequoia et Tahoe.
• 📡 NATIVE_WIFI.md : Implémentation du pilote IO80211Controller, vtable Skywalk macOS Tahoe et table des IOCTLs Apple80211.
• 🛠️ BUILD.md : Guide de compilation, injection dans l'EFI OpenCore et commandes de diagnostic.

---

Compilation

Prérequis

• Xcode 26+ (ex. Xcode 26.6 avec SDK macOS 26.5) sous macOS Tahoe, ou Xcode 16+ sous macOS Sequoia.
• Outils en ligne de commande Xcode (xcode-select --install).

Lancer la compilation

Dans le terminal, exécutez la commande suivante à la racine du projet :

xcodebuild -project QualcommWireless.xcodeproj -configuration Release

Le bundle kext final est généré dans : build/Release/QualcommWireless.kext

Il s'agit d'un binaire universel supportant nativement x86_64 (Hackintosh Intel/AMD) et arm64e (Apple Silicon).

---

Installation avec OpenCore

1. Copier le Kext : Montez votre partition EFI et copiez QualcommWireless.kext dans EFI/OC/Kexts/.

2. Ajouter dans config.plist : Dans la section Kernel -> Add :

   <dict>
       <key>Arch</key>
       <string>Any</string>
       <key>BundlePath</key>
       <string>QualcommWireless.kext</string>
       <key>Comment</key>
       <string>Qualcomm FastConnect 7800 Wi-Fi & Bluetooth</string>
       <key>Enabled</key>
       <true/>
       <key>ExecutablePath</key>
       <string>Contents/MacOS/QualcommWireless</string>
       <key>MaxKernel</key>
       <string></string>
       <key>MinKernel</key>
       <string></string>
       <key>PlistPath</key>
       <string>Contents/Info.plist</string>
   </dict>
   

3. Arguments de démarrage recommandés (NVRAM -> boot-args) :

   -btlfxallowanyaddr -btlfxnvramcheck
   

---

Résolution des Problèmes & Bonnes Pratiques

Caution

Règle d'or : JAMAIS d'IntelBTPatcher.kext !

Le kext tiers IntelBTPatcher.kext est conçu uniquement pour les puces Intel. Sous macOS 15 Sequoia (Darwin 24), il installe des hooks défaillants dans IOBluetoothFamily qui provoquent un Kernel Panic systématique lors du chargement de la session utilisateur (IOBluetoothL2CAPChannel corrupted the registry).

Assurez-vous qu'IntelBTPatcher.kext est totalement désactivé et supprimé de votre EFI.

Important

Conservation de BlueToolFixup.kext

Le kext BlueToolFixup.kext (issu de la suite Acidanthera) reste nécessaire et doit être conservé dans votre EFI afin de permettre à bluetoothd de prendre en charge les contrôleurs Bluetooth tiers.

---

Licence

Ce projet est distribué sous les termes de la licence BSD-3-Clause. Tous droits réservés.