# 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.