diff --git a/README.md b/README.md new file mode 100644 index 0000000..d434ab8 --- /dev/null +++ b/README.md @@ -0,0 +1,180 @@ +# QualcommWireless + +[![macOS Sequoia](https://img.shields.io/badge/macOS-Sequoia%2015.x-blue.svg)](https://www.apple.com/macos/) +[![Wi-Fi 7](https://img.shields.io/badge/Wi--Fi%207-802.11be-green.svg)](https://en.wikipedia.org/wiki/IEEE_802.11be) +[![Bluetooth 5.4](https://img.shields.io/badge/Bluetooth-5.4%20LE%20Audio-orange.svg)](https://en.wikipedia.org/wiki/Bluetooth) +[![OpenCore](https://img.shields.io/badge/Bootloader-OpenCore-lightgrey.svg)](https://github.com/acidanthera/OpenCorePkg) +[![Architecture](https://img.shields.io/badge/Arch-x86__64%20%7C%20arm64e-purple.svg)]() + +Pilote unifié haute performance pour les modules **Qualcomm FastConnect 7800 (WCN7850)** sous **macOS Sequoia (15.x)** et versions ultérieures. + +Ce projet fournit une prise en charge **Wi-Fi 7 native** intégrée à la pile réseau sans fil Apple (`IO80211Controller`), 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](#présentation-du-matériel) +- [Fonctionnalités Principales](#fonctionnalités-principales) +- [Architecture du Pilote](#architecture-du-pilote) +- [Documentation Technique](#documentation-technique) +- [Compilation](#compilation) +- [Installation avec OpenCore](#installation-avec-opencore) +- [Résolution des Problèmes & Bonnes Pratiques](#résolution-des-problèmes--bonnes-pratiques) +- [Licence](#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`](QualcommWireless/QualcommWifi.hpp), é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`). +- **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 + +```mermaid +graph TD + subgraph macOS["macOS Sequoia 15.x (Darwin 24)"] + 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• apple80211_ioctl\n• BHI/MHI Pipeline\n• BAR0 Windowing"] + QBt["QualcommWireless (IOService)\n• DFU Firmware Upload\n• RAMPATCH + NVM\n• 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/`](docs/) contient une documentation technique exhaustive : + +- 📐 [**ARCHITECTURE.md**](docs/ARCHITECTURE.md) : Détail complet des interactions logicielles et matérielles, pipelines firmware et topologies de bus. +- 🔵 [**BLUETOOTH.md**](docs/BLUETOOTH.md) : Analyse post-mortem du crash L2CAP au démarrage de session, séquence DFU et configuration `bluetoothd`. +- 📡 [**NATIVE_WIFI.md**](docs/NATIVE_WIFI.md) : Implémentation du pilote `IO80211Controller`, table des IOCTLs Apple80211 et gestion Wi-Fi 7. +- 🛠️ [**BUILD.md**](docs/BUILD.md) : Guide de compilation, injection dans l'EFI OpenCore et commandes de diagnostic. + +--- + +## Compilation + +### Prérequis +- Xcode 15+ ou 16+ sous macOS Sonoma ou 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 : + +```bash +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` : + ```xml + + Arch + Any + BundlePath + QualcommWireless.kext + Comment + Qualcomm FastConnect 7800 Wi-Fi & Bluetooth + Enabled + + ExecutablePath + Contents/MacOS/QualcommWireless + MaxKernel + + MinKernel + + PlistPath + Contents/Info.plist + + ``` + +3. **Arguments de démarrage recommandés** (`NVRAM -> boot-args`) : + ```text + -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](LICENSE). Tous droits réservés.