Erwan
d152d81d79
- Breakthroughs & Rétro-ingénierie :
* Création de docs/RESEARCH_AND_REVERSE_ENGINEERING.md : synthèse exhaustive
de toutes les recherches théoriques, des contraintes matérielles du WCN7850
(MMIO BAR0 windowing 0x310c, DMA 36-bit page mask, désactivation ASPM L0s/L1),
de la machine d'état du protocole MHI/BHIe (bootloader 2-étapes FBC, anneaux
CR/ER/TR, environnement d'exécution AMSS/WFW), ainsi que du reverse-engineering
complet de l'ABI et de la vtable IO80211Controller (3728 octets, 466 entrées,
graphe d'appels de start(), slots purs et ivars dans BootKernelExtensions.kc).
* Création de docs/ISSUES_AND_POSTMORTEMS.md : historique détaillé et
chronologique de l'ensemble des 9 incidents, bugs et panics rencontrés
depuis le début du projet (erreurs de link KPI, padslot mismatch OpenCore,
panique explicite Apple _panic("No ivars->_faultReporter"), échec RNGAgent,
cycle Kext OSBundleRequired Network-Root, et reboots intempestifs), avec
symptômes, analyses de cause racine, et résolutions techniques validées.
* Mise à jour de docs/ARCHITECTURE.md : référencement croisé des nouveaux
documents d'ingénierie et de post-mortems.
- Validation :
* Arborescence documentaire consolidée et intègre.
* Validation syntaxique et liens Markdown vérifiés.
117 lines
6.2 KiB
Markdown
117 lines
6.2 KiB
Markdown
# Architecture de QualcommWireless
|
|
|
|
Ce document détaille l'architecture logicielle et matérielle du pilote unifié **QualcommWireless** pour les puces combinées **Qualcomm FastConnect 7800** (SoC WCN7850) sous **macOS Tahoe (26.x / Darwin 25)** et **macOS Sequoia (15.x / Darwin 24)**.
|
|
|
|
---
|
|
|
|
## 1. Vue d'Ensemble du Matériel WCN7850
|
|
|
|
Le module sans fil Qualcomm FastConnect 7800 (WCN7850) utilise une architecture à double bus physique :
|
|
|
|
```mermaid
|
|
graph TD
|
|
subgraph Host["Système Hôte (macOS Tahoe - Darwin 25 / Sequoia - Darwin 24)"]
|
|
subgraph Kernel["Kernel Space (XNU / IOKit)"]
|
|
IO80211["com.apple.iokit.IO80211Family\n(IO80211Controller)"]
|
|
IOUSB["com.apple.iokit.IOUSBHostFamily\n(IOUSBHostDevice / Interface)"]
|
|
QWifi["QualcommWifi.kext\n(Driver Wi-Fi 7 Natif)"]
|
|
QBt["QualcommWireless.kext\n(Initialisation & Firmware BT)"]
|
|
end
|
|
subgraph Userland["Espace Utilisateur"]
|
|
AirportD["airportd / CoreWLAN / Control Center"]
|
|
BtD["bluetoothd / IOBluetoothFamily daemon"]
|
|
end
|
|
end
|
|
|
|
subgraph Hardware["Qualcomm FastConnect 7800 (WCN7850)"]
|
|
subgraph PCIeBus["Bus PCIe Gen3 x1 (VID 0x17cb, PID 0x1107)"]
|
|
BAR0["MMIO BAR0 (512 Ko)"]
|
|
Windowing["Registre Fenêtrage (0x310c)"]
|
|
BHI["Boot Host Interface (BHI/BHIe)"]
|
|
MHI["Modem Host Interface (MHI v1.0)"]
|
|
AMSS["Firmware Wi-Fi 7 (AMSS)"]
|
|
end
|
|
subgraph USBBus["Bus USB 2.0 (VID 0x0489, PID 0xe10d)"]
|
|
EP0["Contrôle EP0 (Requêtes Vendeur QCA)"]
|
|
EP2["Bulk OUT EP2 (DFU Firmware Upload)"]
|
|
EP1["Interrupt IN EP1 (Événements HCI)"]
|
|
ROM["ROM Qualcomm & Patch RAM"]
|
|
end
|
|
end
|
|
|
|
AirportD -->|Apple80211 IOCTL / Skywalk| IO80211
|
|
IO80211 --> QWifi
|
|
QWifi -->|BAR0 Windowing / MHI / Ring DMA| BAR0
|
|
BAR0 --> Windowing
|
|
Windowing --> BHI
|
|
BHI --> AMSS
|
|
|
|
BtD -->|UserClient / HCI Packets| IOUSB
|
|
IOUSB --> QBt
|
|
QBt -->|DFU Rampatch & NVM| EP2
|
|
QBt -->|HCI Reset| EP0
|
|
```
|
|
|
|
### Caractéristiques Physiques
|
|
1. **Partie Wi-Fi (PCIe)** :
|
|
- Identifiant : `0x17cb:0x1107`
|
|
- Protocole : 802.11a/b/g/n/ac/ax/be (Wi-Fi 7)
|
|
- Bandes de fréquence : 2.4 GHz, 5 GHz, 6 GHz
|
|
- Largeur de canal maximale : 320 MHz, modulation 4096-QAM
|
|
- Débit théorique : jusqu'à 5.8 Gbps
|
|
- Bus d'interface : PCI Express Gen3 x1
|
|
|
|
2. **Partie Bluetooth (USB)** :
|
|
- Identifiant : `0x0489:0xe10d` (Foxconn / Hon Hai WCN7850 HCI)
|
|
- Spécification : Bluetooth 5.4, LE Audio, Auracast
|
|
- Bus d'interface : USB 2.0 haute fidélité (connecté en interne sur port USB de la carte mère)
|
|
|
|
---
|
|
|
|
## 2. Découpage du Pilote Kernel
|
|
|
|
Le pilote est structuré en deux classes IOKit distinctes et complémentaires au sein du bundle :
|
|
|
|
### 2.1. `QualcommWifi` (`IO80211Controller`)
|
|
- **Rôle** : Pilote Wi-Fi natif.
|
|
- **Classe parente** : `IO80211Controller` (de `com.apple.iokit.IO80211Family`).
|
|
- **Fournisseur (Provider)** : `IOPCIDevice` (`pci17cb,1107`).
|
|
- **Gestion MMIO & Fenêtrage** :
|
|
- La mémoire de configuration et de contrôle du WCN7850 s'étend sur plusieurs mégaoctets de registres internes, mais le BAR0 PCIe n'expose qu'une fenêtre de 512 Ko.
|
|
- Le pilote implémente le fenêtrage dynamique Qualcomm via le registre `0x310c` (`ATH12K_PCI_WINDOW_REG_ADDRESS`). Pour toute adresse au-delà de 512 Ko, l'offset de fenêtre est programmé à la volée.
|
|
- **Cycle de vie du Firmware MHI / BHI** :
|
|
1. Reset global du SoC (`0x3008`).
|
|
2. Lecture de la révision matérielle TCSR (`0x1B00000`).
|
|
3. Allocation des descripteurs DMA 36-bit alignés sur 4 Ko (`ATH12K_DMA_MASK_36BIT_PAGE`).
|
|
4. Initialisation du Boot Host Interface (BHI).
|
|
5. Chargement en mémoire des firmwares `amss.bin`, `m3.bin`, et `board-2.bin`.
|
|
6. Transition de l'environnement d'exécution (Execution Environment) de `PBL` (Primary Boot Loader) vers `AMSS`.
|
|
7. Établissement des anneaux de commande, d'événements et de données MHI (M0 State).
|
|
- **Intégration macOS 802.11** :
|
|
- Traitement natif des commandes IOCTL `APPLE80211_IOC_*` (SSID, scan passif/actif, BSSID list, RSSI, canal, association).
|
|
- Fourniture d'une véritable interface sans fil reconnue par le Centre de Contrôle et `airportd`.
|
|
|
|
### 2.2. `QualcommWireless` (`IOService`)
|
|
- **Rôle** : Initialisation du contrôleur Bluetooth USB et téléversement du Rampatch & NVM.
|
|
- **Classe parente** : `IOService`.
|
|
- **Fournisseur (Provider)** : `IOUSBHostDevice` (`0x0489:0xe10d`).
|
|
- **Protocole de démarrage** :
|
|
1. Interrogation de la version matérielle (`QCA_GET_TARGET_VERSION`).
|
|
2. Vérification de l'état du microprogramme (`QCA_CHECK_STATUS`).
|
|
3. Téléversement du RAMPATCH binaire (`rampatch_usb_00190200_bin`) via le pipe Bulk OUT (EP2) avec header DFU de 40 octets.
|
|
4. Téléversement de la configuration NVRAM (`nvm_usb_00190200_bin`) avec header DFU de 4 octets.
|
|
5. Envoi d'un `HCI_Reset` (`0x03, 0x0c, 0x00`) via requête de contrôle USB.
|
|
6. Injection des métadonnées `IORegistry` (`USB Product Name`, `kUSBHostPortType=255`, spoofing `idVendor=0x0a12`).
|
|
7. Fermeture propre des pipes et libération de l'accès exclusif afin que le daemon `bluetoothd` prenne la main sans conflit.
|
|
|
|
|
|
---
|
|
|
|
## 3. Documentation Complémentaire & Analyse Approfondie
|
|
|
|
- [Recherche Approfondie & Rétro-Ingénierie Kernel](file:///Users/erwan/Documents/QualcommWireless/docs/RESEARCH_AND_REVERSE_ENGINEERING.md) : Analyse binaire de `BootKernelExtensions.kc`, ABI `IO80211Controller`, call graph de `start()`, slots de vtable et spécifications MHI/BHIe.
|
|
- [Historique des Problèmes & Post-Mortems](file:///Users/erwan/Documents/QualcommWireless/docs/ISSUES_AND_POSTMORTEMS.md) : Analyse détaillée des panics (`_faultReporter`, WorkQueue, vtables, ASPM, DMA 36-bit) et résolutions techniques.
|
|
- [Implémentation Wi-Fi Natif](file:///Users/erwan/Documents/QualcommWireless/docs/NATIVE_WIFI.md) : Détails sur l'architecture Skywalk et les commandes Apple80211.
|
|
- [Implémentation Bluetooth 5.4](file:///Users/erwan/Documents/QualcommWireless/docs/BLUETOOTH.md) : Détails sur le protocole DFU Qualcomm et l'injection IORegistry.
|
|
- [Guide de Compilation](file:///Users/erwan/Documents/QualcommWireless/docs/BUILD.md) : Procédure de build, signatures et déploiement OpenCore.
|