Added : README.md for general comprehension
This commit is contained in:
nawrhehe committed
1 parent
b03b6c8197
commit
5f28381754
1 file changed
+180
@@ -0,0 +1,180 @@
|
||||
# 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 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
|
||||
<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.
|
||||
Reference in new issue
Block a user