QualcommWireless/docs/RESEARCH_AND_REVERSE_ENGINEERING.md

Recherche Approfondie & Rétro-Ingénierie : Qualcomm WCN7850 & macOS Tahoe (Darwin 25)

Ce document consigne l'ensemble des recherches théoriques, des analyses matérielles, du reverse-engineering binaire du noyau macOS et des découvertes d'ABI effectuées pour le développement du pilote Wi-Fi natif QualcommWifi.

---

1. Matériel & Architecture PCIe du Qualcomm WCN7850

1.1. Identification Matérielle

• Puce : Qualcomm FastConnect 7800 (WCN7850)
• Identifiants PCI :
  • Vendor ID : 0x17cb (Qualcomm Inc.)
  • Device ID : 0x1107 (WCN7850 Wi-Fi 7 PCIe Adapter)
  • Subsystem Vendor : 0x0000, Subsystem ID : 0x0000
• Architecture Dual-Radio :
  • La puce intègre sur le même die le contrôleur Wi-Fi 7 (connecté via bus PCIe Gen 3/4) et le contrôleur Bluetooth 5.4 (connecté via bus USB interne 0x0cf3:0xe005 / 0xe007 / 0xe300).
  • Le Bluetooth fonctionne de manière autonome via QualcommWireless.kext (transport USB HCI + patches BlueToolFixup).

1.2. Espace Mémoire MMIO BAR0 & Mécanisme de Fenêtrage PCIe

Le contrôleur PCIe n'expose qu'une région BAR0 de 512 Ko (0x80000 octets). L'architecture interne du WCN7850 (SoC, processeurs AMSS, mémoires partagées, registres MHI) nécessite un adressage sur plus de 8 Mo.

• Registre de sélection de fenêtre BAR0 : 0x310c (ATH12K_PCI_WINDOW_REG_ADDRESS).
• Algorithme de fenêtrage dynamique : Pour tout offset matériel A \ge \text{0x80000} : \text{window} = (A \gg 19) \ \& \ 0x3F \text{window\_reg\_val} = 0x80000000 \ | \ \text{window} \text{bar0\_target\_offset} = 0x80000 \ | \ (A \ \& \ 0x7FFFF)
• Observation : Le bit 31 (0x80000000) valide la sélection de la fenêtre active. Le pilote maintient un cache fCurrWindow pour éviter des écritures redondantes sur le bus PCIe.

1.3. Contraintes DMA 36-bit sur Architecture AMD x86_64

• Le moteur DMA interne du WCN7850 utilise des pointeurs physiques limités à 36 bits d'adresse (ATH12K_DMA_MASK_36BIT_PAGE = 0xFFFFFF000ULL, soit 64 Go d'espace physique adressable).
• Tout tampon alloué sans masque physique au-delà de 64 Go entraîne des écritures DMA tronquées, provoquant des corruptions de mémoire ou des redémarrages instantanés.
• Règle absolue : Les buffers DMA d'anneaux MHI et de transfert firmware doivent impérativement être instanciés via :

  IOBufferMemoryDescriptor::inTaskWithPhysicalMask(
      kernel_task,
      kIODirectionInOut | kIOMemoryPhysicallyContiguous,
      taille,
      0xFFFFFF000ULL
  );
  

1.4. ASPM (Active State Power Management)

• Pendant le transfert du Secondary Boot Loader (SBL) ou de l'image AMSS, le passage automatique du lien PCIe en mode basse consommation (L0s ou L1) entraîne la perte de synchronisation des horloges MMIO et le blocage de la machine d'état BHIe.
• Solution : Désactivation explicite d'ASPM dans le registre Link Control de la capacité PCIe (pciCapOffset + 0x10) en masquant les bits 0 et 1 (linkCtrl &= ~0x3).

---

2. Protocole MHI (Modem Host Interface) & Bootloader BHI/BHIe

Le WCN7850 s'amorce à travers le protocole matériel Qualcomm MHI (Modem Host Interface) :

2.1. Environnements d'Exécution (Execution Environments - EE)

• 0x00 - PBL : Primary Boot Loader (ROM interne au SoC).
• 0x01 - SBL : Secondary Boot Loader (chargé par l'hôte en RAM interne).
• 0x02 - AMSS : Advanced Mobile Subscriber Software (Firmware principal Mission Mode Wi-Fi 7).
• 0x03 - RDDM : RAM Dump Collect (mode crash/debug).
• 0x04 - WFW : WLAN Firmware Active.

2.2. Séquence de Démarrage 2-Étapes (FBC - Full Boot Flow)

1. Découverte des offsets BHI/BHIe : Lecture des registres de configuration MHI :
   • ATH12K_MHI_BHIOFF (0x24) : contient l'offset relatif de base de la BHI.
   • ATH12K_MHI_BHIEOFF (0x28) : contient l'offset relatif de base de la BHIe.
2. Chargement de l'étape 1 (SBL) :
   • Configuration de ATH12K_BHI_IMGADDR_LOW et _HIGH avec l'adresse physique du chunk initial de 512 Ko.
   • Écriture de la taille dans ATH12K_BHI_IMGSIZE.
   • Déclenchement par sonnette BHI : écriture de 1 dans ATH12K_BHI_IMGTXDB.
   • Attente du statut dans ATH12K_BHI_STATUS (vérification du masque 0xC0000000 == 0x80000000).
3. Configuration des Anneaux MHI (MHI Data Structures) :
   • Channel Context Array (CCABAP) : tableau des 64 contextes de canaux (direction, type de transfert, buffers).
   • Event Ring Context Array (ECABAP) : anneaux d'événements matériels (ER0 pour les événements généraux, ER1 pour les paquets de données).
   • Command Ring Context Array (CRCBAP) : anneau de commandes WMI/MHI.
   • Doorbells MHI : programmation des adresses matérielles de sonnette pour notifier le matériel de nouveaux descripteurs.
4. Chargement de l'étape 2 (AMSS FBC via BHIe) :
   • Allocation d'une table vectorielle Scatter-Gather (struct bhi_vec_entry).
   • Découpage de l'image AMSS complète (~6 Mo) en segments de 512 Ko.
   • Programmation des registres ATH12K_BHIE_TXVECADDR_LOW/HIGH, ATH12K_BHIE_TXVECSIZE, et écriture de 1 dans ATH12K_BHIE_TXVECDB.
5. Transition vers l'état Mission M0 :
   • Écriture de l'état ATH12K_MHI_STATE_M0 (2) dans ATH12K_MHI_MHICTRL.
   • Surveillance des interruptions MSI et des événements d'anneau MHI (PKT_TYPE_STATE_CHANGE_EVENT vers M0 et PKT_TYPE_EE_EVENT vers AMSS).

---

3. Reverse-Engineering d'Apple IO80211Controller (macOS Tahoe Darwin 25)

L'analyse a été menée par rétro-ingénierie binaire directe de la Kernel Collection de production : /System/Library/KernelCollections/BootKernelExtensions.kc.

3.1. Structure de la Vtable IO80211Controller

• Emplacement Vtable : 0xffffff8002461148 à 0xffffff8002461fd8.
• Taille exacte : 0xe90 octets (3728 octets) = 466 entrées (2 mots d'en-tête RTTI + 464 slots de méthodes virtuelles).
• Alignement OpenCore : OpenCore valide la taille exacte de la vtable lors du chargement des Kexts (Vtables.c). Tout Kext dérivant d'IO80211Controller sous macOS Tahoe doit impérativement avoir une table virtuelle de 3728 octets sous peine d'échec immédiat (padslot mismatch).

3.2. Méthodes Virtuelles Pures d'Apple (___cxa_pure_virtual)

Le noyau macOS définit 6 slots virtuels purs dans IO80211Controller qui doivent obligatoirement être implémentés par le sous-classeur :

1. Slot 410 (*0xcc0) : IONetworkController::getPacketFilters
2. Slot 411 (*0xcc8) : IONetworkController::enable(IONetworkInterface*)
3. Slot 412 (*0xcd0) : IONetworkController::disable(IONetworkInterface*)
4. Slot 413 (*0xcd8) : IONetworkController::outputPacket(mbuf_t, void*)
5. Slot 414 (*0xce0) : IONetworkController::getHardwareAddress(IOEthernetAddress*)
6. Slot 426 (*0xd40(%rax)) : virtual void* getLogger(void) const = 0;
7. Slot 434 (*0xd80(%rax)) : virtual void* getFaultReporterFromDriver(void) = 0;

3.3. Déroulement Interne de IO80211Controller::start(provider) (0xffffff8002291f30)

L'analyse désassemblée révèle le graphe d'appels complet exécuté lors de super::start(provider) :

1. +0x03b : Invoque IONetworkController::start(provider) (0xffffff80026f34dc).
   • Initialise le WorkLoop réseau et publie les interfaces.
   • Exigence : Nécessite que createWorkQueue() soit surchargé et valide, sinon start retourne false immédiatement.
2. +0x17e : Appelle this->getLogger() (callq *0xd40(%rax), Slot 426).
   • Stocke le résultat à l'offset 0x70 des ivars internes (ivars->_logger).
3. +0x191 : Appelle createIOReporters(provider).
4. +0x25a : Appelle setupControlPathLogging().
   • Vérifie les flags d'événements et de métriques LQML.
5. +0x272 : Appelle findAndAttachToFaultReporter() (0xffffff8002292628).
   • Invoque this->getFaultReporterFromDriver() (callq *0xd80(%rax), Slot 434).
   • Si le pointeur renvoyé est non-nul : appelle obj->retain() (callq *0x20(%rax)), et le stocke dans ivars->_faultReporter (0x58(%ivars)).
   • Comportement si NULL : À 0xffffff8002292737, exécute l'instruction de panic explicite : panic("\"No ivars->_faultReporter\" @IO80211Controller.cpp:2877") !
6. +0x2d0 : Appelle IO80211RangingManager::initWithController(this).
7. +0x2e3 : Appelle this->getWorkQueue() (callq *0xc68(%rax)).
8. +0x2f0 : Instancie IO80211CommandGate::allocWithParams(this, workQueue).
9. +0x471 : Appelle this->CreatePostOffice().
   • Crée la boîte aux lettres d'événements Wi-Fi associée à la workQueue.
10. +0x4ac : Instancie IO80211TimerSource::allocWithParams(2, this, workQueue).
11. +0x4e3 : Instancie IO80211TimerFactory::allocWithParams(workQueue).
12. +0x502 : Appelle IO80211RNGAgent::withOptions(this) (0xffffff80022dd55c).
    • Invoque à son tour this->getLogger(). Si nul, abandonne et renvoie NULL.
    • Si non-nul : appelle logger->retain().
13. +0x521 : Appelle this->allocFramePool().
    • Récupère la taille de trame via le slot 440 (retourne 0x100 = 256).
    • Alloue le pool de buffers réseau via IO80211MallocBufferPool::withOptions().
14. +0x555 : Retourne true (kIOReturnSuccess).

---

4. Intégration Skywalk & airportd sous macOS Tahoe

• Suppression des interfaces réseau Ethernet pour le Wi-Fi : Sous macOS 26.x, le démon airportd ignore les interfaces Wi-Fi déclarées sous forme d'IOEthernetInterface. L'association et la gestion du lien s'effectuent via IO80211SkywalkInterface.
• Méthodes clés de gestion d'état :
  • handleCardSpecific : réceptionne l'ensemble des requêtes APPLE80211_IOC_* provenant d'airportd et du Centre de Contrôle.
  • dataLinkLayerAttachComplete : notifie le pilote dès que la couche Skywalk de transport est connectée.
  • setPOWER / getPOWER : gestion logicielle de l'alimentation de l'émetteur radio.
  • getCARD_CAPABILITIES : publication des capacités matérielles (chiffrements AES/WPA3, largeurs de bande, 802.11be EHT).

4.1. Anatomie Binaire et ABI de IO80211SkywalkInterface (BootKernelExtensions.kc)

L'analyse par désassemblage Capstone a établi l'exactitude de l'interface Skywalk native :

1. Table Virtuelle (__ZTV23IO80211SkywalkInterface) :
   • Contient exactement 461 slots virtuels (0xe68 octets).
   • Slot 184 (+0x5c0) : virtual bool start(IOService *controller) (0xffffff80022f5792).
   • Slot 185 (+0x5c8) : virtual void stop(IOService *controller) (0xffffff80022f885c).
   • Slot 18 (+0x90) : virtual void free(void) (0xffffff80022f6184).
   • Slot 373 (+0xba8) : virtual IO80211Controller* getController(void) (0xffffff80022f957a).
2. Méthodes Non-Virtuelles Essentielles :
   • init(IOService *controller, ether_addr *mac) (0xffffff80022f56e2) : NON-VIRTUELLE. Initialise les ivars internes (this->ivars + 0x120), alloue la structure de contrôle et copie l'adresse MAC (6 octets) dans ivars + 0xe4 / +0xe8.
   • setInterfaceRole(UInt32 role) (0xffffff80022f60f0) : NON-VIRTUELLE. Configure le rôle réseau dans this->ivars + 0x58 (role = 1 pour kIO80211InterfaceRoleInfra).
3. Attachement au Contrôleur (IO80211Controller) :
   • Slot 441 (+0xdc8, 0xffffff8002295fce) : bool attachInterface(OSObject *iface, IOService *unused = nullptr). Vérifie OSDynamicCast(IO80211SkywalkInterface, iface) et valide iface->ivars->role == 1, puis enregistre l'interface primaire dans controller->ivars + 0x188.
   • Slot 442 (+0xdd0, 0xffffff800229604a) : bool detachInterface(OSObject *iface, bool arg2 = false). Détache l'interface et réinitialise controller->ivars + 0x188 = NULL.