### ItlHalService Usage Example

Source: https://context7.com/openintelwireless/itlwm/llms.txt

Demonstrates how to instantiate and initialize the correct concrete subclass of `ItlHalService` based on the PCI device ID. This code would typically be found within the `start()` method of the `itlwm` or `AirportItlwm` controllers.

```cpp
// Usage: instantiate the correct concrete subclass based on PCI device ID
// (itlwm / AirportItlwm do this inside start())
ItlHalService *hal = nullptr;
if (/* MVM Gen2 device */) {
    hal = OSTypeAlloc(ItlIwm);
} else if (/* AX series */) {
    hal = OSTypeAlloc(ItlIwx);
} else {
    hal = OSTypeAlloc(ItlIwn);
}
hal->initWithController(this, getWorkLoop(), commandGate);
hal->attach(pciNub);   // loads firmware, maps registers
hal->enable(netif);    // starts radio
```

--------------------------------

### Get Runtime Driver Metrics with ItlDriverInfo

Source: https://context7.com/openintelwireless/itlwm/llms.txt

Use ItlDriverInfo to retrieve read-only runtime state of the current hardware/firmware. Implementations are provided by HAL backends and accessed via ItlHalService::getDriverInfo().

```cpp
// include/HAL/ItlDriverInfo.hpp

class ItlDriverInfo {
public:
    // Returns the loaded firmware version string, e.g. "68.1da39a26.0 QuZ"
    virtual const char *getFirmwareVersion() = 0;

    // Returns the firmware file name used, e.g. "iwlwifi-QuZ-a0-hr-b0-68.ucode"
    virtual const char *getFirmwareName() = 0;

    // Returns the regulatory country code programmed in NVM, e.g. "US"
    virtual const char *getFirmwareCountryCode() = 0;

    // Returns ambient BSS noise floor in dBm
    virtual int16_t getBSSNoise() = 0;

    // Returns true if the NIC supports 5 GHz operation
    virtual bool is5GBandSupport() = 0;

    // Returns the number of TX spatial streams (NSS)
    virtual int getTxNSS() = 0;

    // Returns driver capability flags (used by AirportItlwm IOCTL handlers)
    virtual UInt32 supportedFeatures() = 0;

    // Returns the hardware TX queue depth
    virtual uint32_t getTxQueueSize() = 0;
};

// Example: reading info from user-space via ItlNetworkUserClient
ItlDriverInfo *info = driver->fHalService->getDriverInfo();
printf("Firmware : %s (%s)\n", info->getFirmwareName(),
                                info->getFirmwareVersion());
printf("Country  : %s\n",      info->getFirmwareCountryCode());
printf("5GHz     : %s\n",      info->is5GBandSupport() ? "yes" : "no");
printf("TX NSS   : %d\n",      info->getTxNSS());
printf("Noise    : %d dBm\n",  info->getBSSNoise());
```

--------------------------------

### ItlNetworkUserClient::externalMethod Dispatch Logic

Source: https://context7.com/openintelwireless/itlwm/llms.txt

This C++ code snippet shows the externalMethod dispatcher in ItlNetworkUserClient. It handles distinguishing between get and set operations using IOCTL_MASK and dispatches to the appropriate static handler method.

```cpp
// itlwm/ItlNetworkUserClient.cpp

IOReturn ItlNetworkUserClient::externalMethod(
    uint32_t selector,
    IOExternalMethodArguments *arguments,
    IOExternalMethodDispatch *dispatch,
    OSObject *target,
    void *reference)
{
    bool isSet = selector & IOCTL_MASK;       // high bit = write
    selector  &= ~IOCTL_MASK;                 // strip mask for table index
    if (selector < 0 || selector > IOCTL_ID_MAX)
        return super::externalMethod(selector, arguments, NULL, this, NULL);

    // structureInput used for SET, structureOutput used for GET
    void *data = isSet ? (void *)arguments->structureInput
                       : (void *)arguments->structureOutput;
    if (!data) return kIOReturnError;
    return sMethods[selector](this, data, isSet);   // dispatch to handler
}
```

--------------------------------

### Reading Driver Information

Source: https://context7.com/openintelwireless/itlwm/llms.txt

Demonstrates how to retrieve driver and firmware version information, as well as the BSD interface name, using the IOCTL_80211_DRIVER_INFO command.

```APIDOC
## Reading Driver Information

### Description
Retrieves the driver version, firmware version, and BSD name of the network interface.

### Method
`IOConnectCallStructMethod` with `IOCTL_80211_DRIVER_INFO` selector.

### Parameters
- `conn`: An `io_connect_t` representing the connection to the itlwm service.
- `selector`: `IOCTL_80211_DRIVER_INFO` (0).
- `inputStruct`: `NULL`.
- `inputSize`: 0.
- `outputStruct`: A pointer to a `struct ioctl_driver_info` to store the results.
- `outputSize`: Pointer to the size of the output structure.

### Request Example
```c
#include <IOKit/IOKitLib.h>
#include <ClientKit/Common.h>

io_service_t service = IOServiceGetMatchingService(
    kIOMasterPortDefault,
    IOServiceMatching("itlwm"));
io_connect_t conn;
IOServiceOpen(service, mach_task_self(), 0, &conn);

struct ioctl_driver_info info = {};
size_t outSize = sizeof(info);
IOConnectCallStructMethod(conn, IOCTL_80211_DRIVER_INFO,
                          NULL, 0, &info, &outSize);
printf("Driver : %s\nFW     : %s\nIface  : %s\n",
       info.driver_version, info.fw_version, info.bsd_name);

IOServiceClose(conn);
```

### Response
#### Success Response
- `driver_version` (string) - The version of the itlwm driver.
- `fw_version` (string) - The version of the firmware.
- `bsd_name` (string) - The BSD name of the network interface (e.g., en1).

#### Response Example
```
Driver : 2.4.0_abc1234
FW     : 68.1da39a26.0 QuZ
Iface  : en1
```
```

--------------------------------

### Reading Driver and Station Info via IOConnectCallStructMethod

Source: https://context7.com/openintelwireless/itlwm/llms.txt

Demonstrates how to read driver and station information using IOConnectCallStructMethod. Ensure necessary headers are included and the service is opened before making calls.

```cpp
#include <IOKit/IOKitLib.h>
#include <ClientKit/Common.h>

io_service_t service = IOServiceGetMatchingService(
    kIOMasterPortDefault,
    IOServiceMatching("itlwm"));
io_connect_t conn;
IOServiceOpen(service, mach_task_self(), 0, &conn);
```

```cpp
// GET driver info (isSet=false → selector without IOCTL_MASK)
struct ioctl_driver_info info = {};
size_t outSize = sizeof(info);
IOConnectCallStructMethod(conn, IOCTL_80211_DRIVER_INFO,
                          NULL, 0, &info, &outSize);
printf("Driver : %s\nFW     : %s\nIface  : %s\n",
       info.driver_version, info.fw_version, info.bsd_name);
```

```cpp
// GET current station info
struct ioctl_sta_info sta = {};
outSize = sizeof(sta);
IOConnectCallStructMethod(conn, IOCTL_80211_STA_INFO,
                          NULL, 0, &sta, &outSize);
printf("SSID: %.32s  RSSI: %d dBm  Rate: %u Mbps  BW: %u MHz  Chan: %u\n",
       sta.ssid, sta.rssi, sta.rate, sta.band_width, sta.channel);
```

```cpp
// SET associate (selector | IOCTL_MASK)
struct ioctl_associate assoc = { .version = IOCTL_VERSION };
strncpy(assoc.nwid.nwid, "MyNetwork", NWID_LEN);
assoc.nwid.len = strlen("MyNetwork");
strncpy(assoc.wpa_key.key, "s3cr3tpassword", WPA_KEY_LEN);
assoc.wpa_key.len = strlen("s3cr3tpassword");
IOConnectCallStructMethod(conn,
    IOCTL_80211_ASSOCIATE | IOCTL_MASK,   // 0x800006
    &assoc, sizeof(assoc), NULL, NULL);
```

```cpp
IOServiceClose(conn);
```

--------------------------------

### Run fw_gen.sh Build Script

Source: https://context7.com/openintelwireless/itlwm/llms.txt

This script is intended to be called as an Xcode "Run Script" build phase. It requires a firmware directory specified by the -P flag.

```bash
scripts/fw_gen.sh -P itlwm/firmware/
```

--------------------------------

### Firmware Build Tool - zlib_compress_fw.py

Source: https://context7.com/openintelwireless/itlwm/llms.txt

Command to manually invoke the firmware compression script. This script is normally run automatically by the Xcode build phase to embed firmware files as zlib-compressed C arrays.

```bash
# Manual invocation (normally run by Xcode build phase):
python3 scripts/zlib_compress_fw.py include/FwBinary.cpp itlwm/firmware/

# The generated FwBinary.cpp contains, for each firmware file:
#   const unsigned char iwlwifi_QuZ_a0_hr_b0_68_ucode[] = { 0x78, 0x9C, ... };
#   const long int      iwlwifi_QuZ_a0_hr_b0_68_ucode_size = sizeof(...);
#
#   const struct FwDesc fwList[] = {
#       {IWL_FW("iwlwifi-QuZ-a0-hr-b0-68.ucode",
#               iwlwifi_QuZ_a0_hr_b0_68_ucode,

```

--------------------------------

### Xcode Build Command for AirportItlwm

Source: https://context7.com/openintelwireless/itlwm/llms.txt

Command to build the AirportItlwm kext using Xcode. The GIT_COMMIT argument is used for versioning.

```bash
xcodebuild -scheme "AirportItlwm (all)" -configuration Release \
           -derivedDataPath build GIT_COMMIT=_abc1234
```

--------------------------------

### kext Load/Unload Scripts for itlwm

Source: https://context7.com/openintelwireless/itlwm/llms.txt

Shell scripts for managing the itlwm kext during development. Includes unloading existing kexts, setting permissions, loading debug builds, and verifying the network interface.

```bash
# scripts/load.sh — unload any existing itlwm, fix permissions, load debug build
sudo kextunload -b com.zxystd.itlwm
sudo chown -R root:wheel ../Build/Products/Debug/itlwm.kext
sudo kextutil -v 6 ../Build/Products/Debug/itlwm.kext

# scripts/unload.sh — unload by path or bundle ID
sudo kextunload ../Build/Products/Debug/itlwm.kext
sudo kextunload -b com.zxystd.itlwm

# Verify the kext is running and the network interface appeared:
kextstat | grep itlwm
ifconfig en1          # or the assigned BSD name from ioctl_driver_info.bsd_name

# Full build + load cycle (itlwm kext):
xcodebuild -scheme itlwm -configuration Debug \
           -derivedDataPath build GIT_COMMIT=_dev
sudo kextunload -b com.zxystd.itlwm 2>/dev/null || true
sudo chown -R root:wheel build/Build/Products/Debug/itlwm.kext
sudo kextutil -v 6 build/Build/Products/Debug/itlwm.kext
```

--------------------------------

### Load and Decompress Firmware with FwData

Source: https://context7.com/openintelwireless/itlwm/llms.txt

FwData provides a mechanism to embed and retrieve zlib-compressed firmware blobs at build time. Use getFWDescByName() to locate and uncompressFirmware() to decompress the firmware image.

```cpp
// include/FwData.h

// Firmware descriptor — name, compressed byte array, compressed size
struct FwDesc {
    const char *name;
    const unsigned char *var;
    const int size;
};

// Look up a firmware blob by file name; returns an OSData* (caller releases)
static inline OSData *getFWDescByName(const char *name);

// Decompress a zlib-deflated firmware image in one shot
// dest/destLen: output buffer (caller allocates; destLen updated on success)
// source/sourceLen: compressed input data
// Returns true on success
static inline bool uncompressFirmware(unsigned char *dest, uint *destLen,
                                      unsigned char *source, uint sourceLen);

// --- Example: loading firmware in ItlIwm::fw_load() ---

// 1. Fetch compressed blob from the embedded registry
OSData *fwBlob = getFWDescByName("iwlwifi-QuZ-a0-hr-b0-68.ucode");
if (!fwBlob) {
    IOLog("Firmware not found\n");
    return kIOReturnNotFound;
}

// 2. Allocate output buffer (firmware files are typically 1–2 MB uncompressed)
uint uncompressedLen = 2 * 1024 * 1024;
unsigned char *uncompressed = (unsigned char *)IOMalloc(uncompressedLen);

// 3. Decompress
bool ok = uncompressFirmware(uncompressed, &uncompressedLen,
                              (unsigned char *)fwBlob->getBytesNoCopy(),
                              (uint)fwBlob->getLength());
fwBlob->release();
if (!ok) {
    IOFree(uncompressed, 2 * 1024 * 1024);
    return kIOReturnError;
}

// 4. Parse and DMA-transfer firmware sections to device
// uncompressed now contains the raw .ucode image, uncompressedLen bytes
```

--------------------------------

### ItlHalService Class Methods

Source: https://context7.com/openintelwireless/itlwm/llms.txt

The ItlHalService class provides an abstract interface for hardware-specific drivers. It manages the lifecycle of the wireless adapter and provides access to network state and driver information.

```APIDOC
## ItlHalService

`ItlHalService` is the abstract IOKit `OSObject` subclass that every hardware-generation driver (`ItlIwm`, `ItlIwx`, `ItlIwn`) must implement. It provides lifecycle management (attach/detach/enable/disable), access to the shared 802.11 controller state (`ieee80211com`), and factory accessors for the per-driver info and controller interfaces.

### Methods

- **`virtual bool attach(IOPCIDevice *device)`**
  Called when the PCI device is matched; maps memory, loads firmware.

- **`virtual void detach(IOPCIDevice *device)`**
  Called on kext unload or device removal.

- **`virtual IOReturn enable(IONetworkInterface *interface)`**
  Brings radio up; called by IOEthernetController::enable().

- **`virtual IOReturn disable(IONetworkInterface *interface)`**
  Brings radio down; called by IOEthernetController::disable().

- **`virtual struct ieee80211com *get80211Controller()`**
  Returns the shared net80211 controller state machine.

- **`virtual ItlDriverInfo *getDriverInfo()`**
  Returns driver information (firmware version, RSSI, features, etc.).

- **`virtual ItlDriverController *getDriverController()`**
  Returns driver control operations (scan, multicast list, etc.).

- **`virtual bool initWithController(IOEthernetController *controller, IOWorkLoop *workloop, IOCommandGate *commandGate)`**
  Must be called before use; wires up the IOCommandGate and IOWorkLoop.

### Protected Methods

- **`int tsleep_nsec(void *ident, int priority, const char *wmesg, int timo)`**
  Sleeps the calling thread inside the command gate; timo in nanoseconds.

- **`void wakeupOn(void *ident)`**
  Wakes threads sleeping on ident.

### Usage Example

```cpp
// Usage: instantiate the correct concrete subclass based on PCI device ID
// (itlwm / AirportItlwm do this inside start())
ItlHalService *hal = nullptr;
if (/* MVM Gen2 device */) {
    hal = OSTypeAlloc(ItlIwm);
} else if (/* AX series */) {
    hal = OSTypeAlloc(ItlIwx);
} else {
    hal = OSTypeAlloc(ItlIwn);
}
hal->initWithController(this, getWorkLoop(), commandGate);
hal->attach(pciNub);   // loads firmware, maps registers
hal->enable(netif);    // starts radio
```
```

--------------------------------

### Associating with a Network

Source: https://context7.com/openintelwireless/itlwm/llms.txt

Initiates a connection to a specified Wi-Fi network using its SSID and WPA PSK.

```APIDOC
## Associating with a Network

### Description
Joins a specified Wi-Fi network by providing the SSID and WPA Pre-Shared Key.

### Method
`IOConnectCallStructMethod` with `IOCTL_80211_ASSOCIATE | IOCTL_MASK` selector.

### Parameters
- `conn`: An `io_connect_t` representing the connection to the itlwm service.
- `selector`: `IOCTL_80211_ASSOCIATE | IOCTL_MASK` (0x800006).
- `inputStruct`: A pointer to a `struct ioctl_associate` containing the network credentials.
- `inputSize`: The size of the `struct ioctl_associate`.
- `outputStruct`: `NULL`.
- `outputSize`: `NULL`.

### Request Body
- `version` (integer) - Must be set to `IOCTL_VERSION` (1).
- `nwid` (struct ioctl_nwid) - Network identifier.
  - `nwid` (char array) - The SSID of the network.
  - `len` (integer) - The length of the SSID.
- `wpa_key` (struct ioctl_wpa_key) - WPA Pre-Shared Key.
  - `key` (char array) - The WPA PSK.
  - `len` (integer) - The length of the WPA PSK.

### Request Example
```c
#include <IOKit/IOKitLib.h>
#include <ClientKit/Common.h>

io_service_t service = IOServiceGetMatchingService(
    kIOMasterPortDefault,
    IOServiceMatching("itlwm"));
io_connect_t conn;
IOServiceOpen(service, mach_task_self(), 0, &conn);

struct ioctl_associate assoc = { .version = IOCTL_VERSION };
strncpy(assoc.nwid.nwid, "MyNetwork", NWID_LEN);
assoc.nwid.len = strlen("MyNetwork");
strncpy(assoc.wpa_key.key, "s3cr3tpassword", WPA_KEY_LEN);
assoc.wpa_key.len = strlen("s3cr3tpassword");
IOConnectCallStructMethod(conn,
    IOCTL_80211_ASSOCIATE | IOCTL_MASK,   // 0x800006
    &assoc, sizeof(assoc), NULL, NULL);

IOServiceClose(conn);
```

### Response
No specific response body is detailed for success in the source. An error would typically be indicated by the return value of `IOConnectCallStructMethod`.
```

--------------------------------

### AirportItlwm Class Method Signatures

Source: https://context7.com/openintelwireless/itlwm/llms.txt

Key method signatures for the AirportItlwm class, which subclasses IO80211Controller. These methods handle IOKit lifecycle, IOCTL dispatching, association, power management, and RSN supplicant integration.

```cpp
class AirportItlwm : public IO80211Controller {
public:
    // IOKit lifecycle
    virtual bool   start(IOService *provider) override;
    virtual void   stop(IOService *provider)  override;
    virtual IOReturn enable(IONetworkInterface *netif)  override;
    virtual IOReturn disable(IONetworkInterface *netif) override;

    // Central apple80211 IOCTL dispatcher — called by CoreWLAN for every
    // Wi-Fi operation (scan, associate, get RSSI, etc.)
    virtual SInt32 apple80211Request(unsigned int request_type,
                                     int request_number,
                                     IO80211Interface *interface,
                                     void *data) override;

    // Association helpers called from IOCTL handlers
    void associateSSID(uint8_t *ssid, uint32_t ssid_len,
                       const struct ether_addr &bssid,
                       uint32_t authtype_lower, uint32_t authtype_upper,
                       uint8_t *key, uint32_t key_len, int key_index);

    // WPA key installation (called from RSN supplicant callbacks)
    void setPTK(const u_int8_t *key, size_t key_len);
    void setGTK(const u_int8_t *key, size_t key_len,
                u_int8_t kid, u_int8_t *rsc);

    // Apple RSN supplicant opt-in (enables WPA2/WPA3 via Apple's stack)
    virtual bool useAppleRSNSupplicant(IO80211Interface *interface) override;

    // Power management
    virtual IOReturn setPowerState(unsigned long powerStateOrdinal,
                                   IOService *policyMaker) override;

    // Selected GET/SET IOCTL implementations (auto-generated via macros):
    IOReturn getSSID   (OSObject *, struct apple80211_ssid_data *);
    IOReturn setSSID   (OSObject *, struct apple80211_ssid_data *);
    IOReturn getRSSI   (OSObject *, struct apple80211_rssi_data *);
    IOReturn getNOISE  (OSObject *, struct apple80211_noise_data *);
    IOReturn getSTATE  (OSObject *, struct apple80211_state_data *);
    IOReturn getSCAN_RESULT(OSObject *, struct apple80211_scan_result **);
    IOReturn setASSOCIATE  (OSObject *, struct apple80211_assoc_data *);
    IOReturn setDISASSOCIATE(OSObject *);
    IOReturn setCIPHER_KEY (OSObject *, struct apple80211_key *);
};

```

--------------------------------

### ItlHalService Abstract Base Class Definition

Source: https://context7.com/openintelwireless/itlwm/llms.txt

Defines the abstract interface for hardware abstraction services in itlwm. Concrete subclasses implement this for specific Intel Wi-Fi chip generations. Requires `OSObject` and `IOPCIDevice` from IOKit.

```cpp
// include/HAL/ItlHalService.hpp

class ItlHalService : public OSObject {
    OSDeclareAbstractStructors(ItlHalService)
public:
    // Called when the PCI device is matched; maps memory, loads firmware
    virtual bool attach(IOPCIDevice *device) = 0;

    // Called on kext unload or device removal
    virtual void detach(IOPCIDevice *device) = 0;

    // Brings radio up; called by IOEthernetController::enable()
    virtual IOReturn enable(IONetworkInterface *interface) = 0;

    // Brings radio down; called by IOEthernetController::disable()
    virtual IOReturn disable(IONetworkInterface *interface) = 0;

    // Returns the shared net80211 controller state machine
    virtual struct ieee80211com *get80211Controller() = 0;

    // Returns driver information (firmware version, RSSI, features, etc.)
    virtual ItlDriverInfo *getDriverInfo() = 0;

    // Returns driver control operations (scan, multicast list, etc.)
    virtual ItlDriverController *getDriverController() = 0;

    // Must be called before use; wires up the IOCommandGate and IOWorkLoop
    virtual bool initWithController(IOEthernetController *controller,
                                    IOWorkLoop *workloop,
                                    IOCommandGate *commandGate);
protected:
    // Sleeps the calling thread inside the command gate; timo in nanoseconds
    int tsleep_nsec(void *ident, int priority, const char *wmesg, int timo);

    // Wakes threads sleeping on ident
    void wakeupOn(void *ident);
};
```

--------------------------------

### Static Method Table for IOCTL Dispatch

Source: https://context7.com/openintelwireless/itlwm/llms.txt

This C++ code defines the static method table used by ItlNetworkUserClient for dispatching IOCTL calls. The order of methods must correspond to the IOCTL_IDS enum.

```cpp
// Static method table (order must match IOCTL_IDS enum):
const IOControlMethodAction ItlNetworkUserClient::sMethods[IOCTL_ID_MAX] {
    sDRIVER_INFO,    // IOCTL_80211_DRIVER_INFO
    sSTA_INFO,       // IOCTL_80211_STA_INFO
    sPOWER,          // IOCTL_80211_POWER
    sSTATE,          // IOCTL_80211_STATE
    sNW_ID,          // IOCTL_80211_NW_ID
    sWPA_KEY,        // IOCTL_80211_WPA_KEY
    sASSOCIATE,      // IOCTL_80211_ASSOCIATE
    sDISASSOCIATE,   // IOCTL_80211_DISASSOCIATE
    sJOIN,           // IOCTL_80211_JOIN
    sSCAN,           // IOCTL_80211_SCAN
    sSCAN_RESULT,    // IOCTL_80211_SCAN_RESULT
    sTX_POWER_LEVEL, // IOCTL_80211_TX_POWER_LEVEL
    sNW_BSSID,       // IOCTL_80211_NW_BSSID
};
```

--------------------------------

### FwData - Firmware Loading and Decompression

Source: https://context7.com/openintelwireless/itlwm/llms.txt

The FwData mechanism, declared in FwData.h, handles the embedding and retrieval of zlib-compressed firmware blobs at build time. The driver can use getFWDescByName() to locate and uncompress firmware images at runtime.

```APIDOC
## FwData — Firmware Loading and Decompression

`FwData.h` declares the firmware registry mechanism used to embed and retrieve zlib-compressed firmware blobs at build time. The `fw_gen.sh` / `zlib_compress_fw.py` build scripts walk `itlwm/firmware/` and produce `FwBinary.cpp`, which defines `fwList[]` and `fwNumber`. At runtime the driver calls `getFWDescByName()` to locate and decompress the required firmware image.

```cpp
// include/FwData.h

// Firmware descriptor — name, compressed byte array, compressed size
struct FwDesc {
    const char *name;
    const unsigned char *var;
    const int size;
};

// Look up a firmware blob by file name; returns an OSData* (caller releases)
static inline OSData *getFWDescByName(const char *name);

// Decompress a zlib-deflated firmware image in one shot
// dest/destLen: output buffer (caller allocates; destLen updated on success)
// source/sourceLen: compressed input data
// Returns true on success
static inline bool uncompressFirmware(unsigned char *dest, uint *destLen,
                                      unsigned char *source, uint sourceLen);

// --- Example: loading firmware in ItlIwm::fw_load() ---

// 1. Fetch compressed blob from the embedded registry
OSData *fwBlob = getFWDescByName("iwlwifi-QuZ-a0-hr-b0-68.ucode");
if (!fwBlob) {
    IOLog("Firmware not found\n");
    return kIOReturnNotFound;
}

// 2. Allocate output buffer (firmware files are typically 1–2 MB uncompressed)
uint uncompressedLen = 2 * 1024 * 1024;
unsigned char *uncompressed = (unsigned char *)IOMalloc(uncompressedLen);

// 3. Decompress
bool ok = uncompressFirmware(uncompressed, &uncompressedLen,
                              (unsigned char *)fwBlob->getBytesNoCopy(),
                              (uint)fwBlob->getLength());
fwBlob->release();
if (!ok) {
    IOFree(uncompressed, 2 * 1024 * 1024);
    return kIOReturnError;
}

// 4. Parse and DMA-transfer firmware sections to device
// uncompressed now contains the raw .ucode image, uncompressedLen bytes
```
```

--------------------------------

### ItlDriverInfo Interface

Source: https://context7.com/openintelwireless/itlwm/llms.txt

The ItlDriverInfo interface provides read-only access to runtime state information about the currently running hardware and firmware. It is implemented by HAL backends and retrieved via ItlHalService::getDriverInfo().

```APIDOC
## ItlDriverInfo — Runtime Driver Metrics Interface

`ItlDriverInfo` is a pure-virtual C++ interface that exposes read-only runtime state about the currently running hardware/firmware combination. It is implemented by each HAL backend and retrieved via `ItlHalService::getDriverInfo()`.

```cpp
// include/HAL/ItlDriverInfo.hpp

class ItlDriverInfo {
public:
    // Returns the loaded firmware version string, e.g. "68.1da39a26.0 QuZ"
    virtual const char *getFirmwareVersion() = 0;

    // Returns the firmware file name used, e.g. "iwlwifi-QuZ-a0-hr-b0-68.ucode"
    virtual const char *getFirmwareName() = 0;

    // Returns the regulatory country code programmed in NVM, e.g. "US"
    virtual const char *getFirmwareCountryCode() = 0;

    // Returns ambient BSS noise floor in dBm
    virtual int16_t getBSSNoise() = 0;

    // Returns true if the NIC supports 5 GHz operation
    virtual bool is5GBandSupport() = 0;

    // Returns the number of TX spatial streams (NSS)
    virtual int getTxNSS() = 0;

    // Returns driver capability flags (used by AirportItlwm IOCTL handlers)
    virtual UInt32 supportedFeatures() = 0;

    // Returns the hardware TX queue depth
    virtual uint32_t getTxQueueSize() = 0;
};

// Example: reading info from user-space via ItlNetworkUserClient
ItlDriverInfo *info = driver->fHalService->getDriverInfo();
printf("Firmware : %s (%s)\n", info->getFirmwareName(),
                                info->getFirmwareVersion());
printf("Country  : %s\n",      info->getFirmwareCountryCode());
printf("5GHz     : %s\n",      info->is5GBandSupport() ? "yes" : "no");
printf("TX NSS   : %d\n",      info->getTxNSS());
printf("Noise    : %d dBm\n",  info->getBSSNoise());
```
```

--------------------------------

### ItlDriverController Interface

Source: https://context7.com/openintelwireless/itlwm/llms.txt

The ItlDriverController interface provides a minimal set of imperative control operations that upper layers can use to interact with the hardware driver, such as clearing scan state or reprogramming filters.

```APIDOC
## ItlDriverController — Driver Control Interface

`ItlDriverController` is a minimal pure-virtual interface for imperative control operations that the upper layers need to call back into the hardware driver (e.g., clearing stale scan state, reprogramming multicast filters).

```cpp
// include/HAL/ItlDriverController.hpp

class ItlDriverController {
public:
    // Clears scan-in-progress flags; called after a scan completes or times out
    virtual void clearScanningFlags() = 0;

    // Programs the hardware multicast address filter
    // addr: array of IOEthernetAddress; count: number of addresses
    virtual IOReturn setMulticastList(IOEthernetAddress *addr, int count) = 0;
};

// Usage inside AirportItlwm scan completion path:
ItlDriverController *ctrl = fHalService->getDriverController();
ctrl->clearScanningFlags();

// Usage inside setMulticastMode():
IOEthernetAddress addrs[8];
int count = buildMulticastList(addrs, 8);
IOReturn ret = ctrl->setMulticastList(addrs, count);
if (ret != kIOReturnSuccess) {
    IOLog("setMulticastList failed: 0x%08x\n", ret);
}
```
```

--------------------------------

### Reading Station Information

Source: https://context7.com/openintelwireless/itlwm/llms.txt

Retrieves current association statistics, including SSID, RSSI, data rate, bandwidth, and channel.

```APIDOC
## Reading Station Information

### Description
Fetches detailed statistics about the current Wi-Fi association.

### Method
`IOConnectCallStructMethod` with `IOCTL_80211_STA_INFO` selector.

### Parameters
- `conn`: An `io_connect_t` representing the connection to the itlwm service.
- `selector`: `IOCTL_80211_STA_INFO` (1).
- `inputStruct`: `NULL`.
- `inputSize`: 0.
- `outputStruct`: A pointer to a `struct ioctl_sta_info` to store the results.
- `outputSize`: Pointer to the size of the output structure.

### Request Example
```c
#include <IOKit/IOKitLib.h>
#include <ClientKit/Common.h>

io_service_t service = IOServiceGetMatchingService(
    kIOMasterPortDefault,
    IOServiceMatching("itlwm"));
io_connect_t conn;
IOServiceOpen(service, mach_task_self(), 0, &conn);

struct ioctl_sta_info sta = {};
outSize = sizeof(sta);
IOConnectCallStructMethod(conn, IOCTL_80211_STA_INFO,
                          NULL, 0, &sta, &outSize);
printf("SSID: %.32s  RSSI: %d dBm  Rate: %u Mbps  BW: %u MHz  Chan: %u\n",
       sta.ssid, sta.rssi, sta.rate, sta.band_width, sta.channel);

IOServiceClose(conn);
```

### Response
#### Success Response
- `ssid` (string) - The Service Set Identifier of the connected network.
- `rssi` (integer) - The Received Signal Strength Indicator in dBm.
- `rate` (unsigned integer) - The current data transmission rate in Mbps.
- `band_width` (unsigned integer) - The channel bandwidth in MHz.
- `channel` (unsigned integer) - The current operating channel.

#### Response Example
```
SSID: MyNetwork  RSSI: -52 dBm  Rate: 400 Mbps  BW: 80 MHz  Chan: 36
```
```

--------------------------------

### Control Driver Operations with ItlDriverController

Source: https://context7.com/openintelwireless/itlwm/llms.txt

Use ItlDriverController for imperative control operations like clearing scan flags or programming multicast filters. Obtain an instance via ItlHalService::getDriverController().

```cpp
// include/HAL/ItlDriverController.hpp

class ItlDriverController {
public:
    // Clears scan-in-progress flags; called after a scan completes or times out
    virtual void clearScanningFlags() = 0;

    // Programs the hardware multicast address filter
    // addr: array of IOEthernetAddress; count: number of addresses
    virtual IOReturn setMulticastList(IOEthernetAddress *addr, int count) = 0;
};

// Usage inside AirportItlwm scan completion path:
ItlDriverController *ctrl = fHalService->getDriverController();
ctrl->clearScanningFlags();

// Usage inside setMulticastMode():
IOEthernetAddress addrs[8];
int count = buildMulticastList(addrs, 8);
IOReturn ret = ctrl->setMulticastList(addrs, count);
if (ret != kIOReturnSuccess) {
    IOLog("setMulticastList failed: 0x%08x\n", ret);
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.