Erwan
a10e097a7e
Breakthroughs & Reverse Engineering (macOS Tahoe 26.7.1 / Darwin 25.6.0): - Reconstructed the complete 463-slot Skywalk vtable and class layout (0x128 / 296 bytes) of IO80211Controller (__ZTV17IO80211Controller at 0xffffff8002461148) and AppleBCMWLANCore from BootKernelExtensions.kc (IO80211Family 1200.13.1, source 1566.5). - Verified IOUSBHostDevice::deviceRequest vtable slot in Tahoe's BootKernelExtensions.kc (__ZTV15IOUSBHostDevice at 0xffffff8002e72720): confirmed exact match at slot 374 (0x176, byte offset 0xbb0). - Disassembled Tahoe's /usr/sbin/bluetoothd (FindTransportType at 0x10014c700, Found_USB_Dongle at 0x1000e9559, GetProductAndVendorID at 0x1000edf2a) confirming USB transport matching on 'Bluetooth USB Host Controller' and CSR 0x0a12 descriptor spoofing. Code & Build Modifications (v1.1.0): - IO80211Controller.h: Add full 463-slot Tahoe Skywalk vtable declaration (slots 394..462, offsets 0xc50..0xe70) and exact 0x80 filler size when __IO80211_TARGET >= 260000 while preserving legacy compatibility. - QualcommWifi.hpp/.cpp: Implement Tahoe IO80211Controller pure virtual methods (isCommandProhibited, handleCardSpecific, getDRIVER_VERSION, getHARDWARE_VERSION, getCARD_CAPABILITIES, getPOWER, setPOWER, getCOUNTRY_CODE, setCOUNTRY_CODE, setGET_DEBUG_INFO, getLogger, getFaultReporterFromDriver) and guard un-reserved IONetworkController slots 6..7 on SDK 26.5. - QualcommWireless.cpp: Add non-null vtable slot sanity check prior to installing the shadow vtable hook on IOUSBHostDevice::deviceRequest. - project.pbxproj & Info.plist: Upgrade to Xcode 26.6 (MacOSX26.5.sdk), MACOSX_DEPLOYMENT_TARGET = 26.0, __IO80211_TARGET = 260000, and bump version to 1.1.0. - docs & README: Document macOS Tahoe (Darwin 25) architecture, bluetoothd offsets, and Skywalk IO80211Controller ABI.
181 lines
7.6 KiB
Markdown
181 lines
7.6 KiB
Markdown
# QualcommWireless
|
|
|
|
[](https://www.apple.com/macos/)
|
|
[](https://en.wikipedia.org/wiki/IEEE_802.11be)
|
|
[](https://en.wikipedia.org/wiki/Bluetooth)
|
|
[](https://github.com/acidanthera/OpenCorePkg)
|
|
[]()
|
|
|
|
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](#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`](QualcommWifi/QualcommWifi.hpp), 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
|
|
|
|
```mermaid
|
|
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/`](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` sous Sequoia et Tahoe.
|
|
- 📡 [**NATIVE_WIFI.md**](docs/NATIVE_WIFI.md) : Implémentation du pilote `IO80211Controller`, vtable Skywalk macOS Tahoe et table des IOCTLs Apple80211.
|
|
- 🛠️ [**BUILD.md**](docs/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 :
|
|
|
|
```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
|
|
<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`) :
|
|
```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.
|