QualcommWireless/docs/ARCHITECTURE.md

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 :

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.