1# WLAN 2 3 4## Overview 5 6### Function 7 8A wireless LAN (WLAN) allows users to easily connect to a wireless network to transmit and share data and move around within the area and remain connected to the network. The WLAN driver developed based on the Hardware Driver Foundation (HDF) shields hardware component differences and provides stable basic capability interfaces for upper-layer WLAN services, including starting a scan, associating with or disassociating from a hotspot, obtaining or setting MAC addresses, and obtaining link information. 9 10### Basic Concepts 11 12Before development, you need to understand the following basic concepts related to WLAN: 13 14- AP 15 16 A wireless access point (AP) is a central node of a network that provides the wireless access service. Once connecting to the wireless network, the device can access data. 17 18- STA 19 20 A station (STA) is a basic component of a WLAN. Each terminal connected to a WLAN, such as a notebook and a personal digital assistant (PDA), is an STA. 21 22- SSID 23 24 A service set identifier (SSID) identifies a wireless network. Each WLAN has its SSID. 25 26- bssid 27 28 A basic service set identifier (BSSID) is a 48-bit MAC address that uniquely identifies a basic service set on a WLAN. 29 30- Scan 31 32 A terminal device scans the wireless network to obtain visible wireless network information, including the hotspot SSID, operating frequency band, and signal strength. 33 34- Associate 35 36 When a terminal device is associated with a valid hotspot, it can communicate with the AP. A device (STA) can set up a connection with only one AP at a time. 37 38### Working Principles 39 40This document describes how to develop WLAN functions based on the HDF. The following figure shows the WLAN framework. 41 42 43 441. The upper-layer service calls a hardware device interface (HDI) based on service requirements to deliver user-mode messages to the client through the Wi-Fi Protected Access (WPA) layer or hardware abstraction layer (HAL). The WPA layer provides interfaces for setting the encryption mode, associating with a hotspot, setting a channel, and hiding the hotspot. As a supplement to the WPA layer, the HAL provides APIs for setting the country code or MAC address and obtaining channel information. 45 462. The Message module distributes user-mode messages to modules, such as the AP and STA, by component. 47 483. Hdf_Mac80211 defines MAC-layer interfaces for underlying drivers. The command field is delivered to Hdf_Mac80211 and then sent to the WLAN chip firmware through the Bus module. 49 504. The Bus module provides unified bus abstraction interfaces for the upper layer. It shields the differences between kernels by calling the Secure Digital Input Output (SDIO) interfaces provided by the platform layer and encapsulating the USB and PCIe interfaces. The Bus module also encapsulates different types of bus operations in a unified manner to shield differences between chipsets. The interfaces provided by the Bus module simplify and streamline the development of different chip vendors. 51 525. Extensible Authentication Protocol (EAP) over LAN (EAPOL) is a LAN-based extended authentication protocol. It is used to transmit EAP packets between a client and a device (access device or server) so that EAP packets can be transmitted on a LAN to complete the authentication process and enable the device to go online. 53 546. NetDevice creates dedicated network devices to shield differences between OSs. It provides unified interfaces for Wi-Fi drivers, unified HDF NetDevice data structs, and unified management, registration, and deregistration capabilities, and connects to the Linux network device layer on OpenHarmony devices. 55 567. NetBuf encapsulates the unified data structure of the Linux or LiteOS native network data buffer and the operation interfaces for network data. 57 588. The protocol stack works with the NetDevice and NetBuf modules to exchange data flows. 59 60### Constraints 61 62The WLAN driver provides basic capability interfaces for upper-layer WLAN services. The HDI interfaces apply to the standard system, and the HAL interfaces apply to mini and small systems. 63 64## Development Guidelines 65 66### When to Use 67 68The WLAN driver provides basic capability interfaces for upper-layer WLAN services to ensure that users can easily access the wireless network and transmit and share data. Refer to the following when you adapt your WLAN module to OpenHarmony. 69 70### Available APIs 71 72The WLAN module provides the following APIs: 73 741. HDI and HAL APIs for upper-layer services 75 762. APIs for vendors 77 783. WLAN APIs directly called by drivers 79 80- This interfaces provided by the WLAN Driver module for upper-layer services can be used to create or destroy an IWiFi object, and set MAC addresses or transmit power. Table 1 and Table 2 list the C function interfaces generated based on the IDL interface description. For details about the interface declaration, see the IDL files (**/drivers/interface/wlan/v1_1/**). 81 82 **Table 1** wifi_hal.h 83 84 | API| Description| 85 | -------- | -------- | 86 | int32_t WifiConstruct(struct IWiFi \*\*wifiInstance) | Creates an **IWiFi** instance with basic capabilities.| 87 | int32_t WifiDestruct(struct IWiFi \*\*wifiInstance) | Destroys an **IWiFi** instance.| 88 | int32_t (\*start)(struct IWiFi \*) | Creates a channel between the HAL and the driver and obtains the NICs supported by the driver.| 89 | int32_t (\*stop)(struct IWiFi \*) | Stops the channel between the HAL and the driver.| 90 91 **Table 2** wifi_hal_base_feature.h 92 93 | API| Description| 94 | -------- | -------- | 95 | int32_t (\*getFeatureType)(const struct IWiFiBaseFeature \*) | Obtains the feature type.| 96 | int32_t (\*setMacAddress)(const struct IWiFiBaseFeature \*, unsigned char \*, uint8_t) | Sets the MAC address.| 97 | int32_t (\*getDeviceMacAddress)(const struct IWiFiBaseFeature \*, unsigned char \*, uint8_t) | Obtains the device MAC address.| 98 | int32_t (\*setTxPower)(const struct IWiFiBaseFeature \*, int32_t) | Sets the transmit power.| 99 100- The WLAN Driver module also provides APIs that you need to fill in the implementation. These APIs can be used to initialize or deregister a network device, open or stop a network device, and obtain network device status. Table 3 describes some APIs. 101 102 **Table 3** net_device.h 103 104 | API| Description| 105 | -------- | -------- | 106 | int32_t (\*init)(struct NetDevice \*netDev) | Initializes a network device.| 107 | struct NetDevStats \*(\*getStats)(struct NetDevice \*netDev) | Obtains the state of a network device.| 108 | int32_t (\*setMacAddr)(struct NetDevice \*netDev, void \*addr) | Sets the MAC address.| 109 | void (\*deInit)(struct NetDevice \*netDev) | Deinitializes a network device.| 110 | int32_t (\*open)(struct NetDevice \*netDev) | Opens a network device.| 111 | int32_t (\*stop)(struct NetDevice \*netDev) | Stops a network device.| 112 113- The WLAN Driver module provides APIs that you can directly use to create or release a **WifiModule**, connect to or disconnect from a WLAN hotspot, request or release a **NetBuf**, and convert between the **pbuf** struct of Lightweight IP (lwIP) and a **NetBuf**. 114 115 Tables 4 to 6 list the APIs that can be directly called. 116 117 **Table 4** wifi_module.h 118 119 | API| Description| 120 | -------- | -------- | 121 | struct WifiModule \*WifiModuleCreate(const struct HdfConfigWifiModuleConfig \*config) | Creates a **WifiModule**.| 122 | void WifiModuleDelete(struct WifiModule \*module) | Deletes a **WifiModule** and releases its data.| 123 | int32_t DelFeature(struct WifiModule \*module, uint16_t featureType) | Deletes a feature from a **WifiModule**.| 124 | int32_t AddFeature(struct WifiModule \*module, uint16_t featureType,<br> struct WifiFeature \*featureData) | Adds a feature to a **WifiModule**.| 125 126 **Table 5** wifi_mac80211_ops.h 127 128 | API| Description| 129 | -------- | -------- | 130 | int32_t (\*startAp)(NetDevice \*netDev) | Starts an AP.| 131 | int32_t (\*stopAp)(NetDevice \*netDev) | Stops an AP.| 132 | int32_t (\*connect)(NetDevice \*netDev, WifiConnectParams \*param) | Connects to a hotspot.| 133 | int32_t (\*disconnect)(NetDevice \*netDev, uint16_t reasonCode) | Disconnects from a hotspot.| 134 135 **Table 6** hdf_netbuf.h 136 137 | API| Description| 138 | -------- | -------- | 139 | static inline void NetBufQueueInit(struct NetBufQueue \*q) | Initializes a **NetBuf** queue.| 140 | struct NetBuf \*NetBufAlloc(uint32_t size) | Allocates a **NetBuf**.| 141 | void NetBufFree(struct NetBuf \*nb) | Releases a **NetBuf**.| 142 | struct NetBuf \*Pbuf2NetBuf(const struct NetDevice \*netdev, struct pbuf \*lwipBuf) | Converts the **pbuf** structure of lwIP to a **NetBuf**.| 143 | struct pbuf \*NetBuf2Pbuf(const struct NetBuf \*nb) | Converts a **NetBuf** to the **pbuf** structure of lwIP.| 144 145### How to Develop 146 147The WLAN driver framework developed based on the HDF and Platform framework provides a unified driver model for vendors regardless of the OS and system on a chip (SoC). When developing your WLAN driver based on the WLAN driver framework, you need to make adaptation. The following uses the Hi3881 WLAN chip as an example. 148 149#### Configuring the HCS for the Driver 150 151 The HDF configuration source (HCS) includes device configuration and component configuration. 152 153 - Device configuration 154 155 The configuration file contains the power supply, reset, and bus configuration. 156 157 Configuration file path: **vendor/<vendor name>/<device name >/hdf_config/khdf/wifi** 158 159 Configure device parameters in **wlan_platform.hcs** based on the device you use. The following is an example of WLAN platform configuration. 160 ```text 161 hisi :& deviceList { 162 device0 :: deviceInst { 163 deviceInstId = 0; 164 powers { 165 power0 { 166 powerSeqDelay = 0; /* Power sequence delay. */ 167 powerType = 1; /* Power supply type. The value 0 indicates that the device is always on. The value 1 indicates power supply through GPIO. */ 168 gpioId = 1; /* GPIO pin number. */ 169 activeLevel=1; /* Active level. The value 0 indicates low level, and 1 indicates high level. */ 170 } 171 power1 { 172 powerSeqDelay = 0; /* Power sequence delay. */ 173 powerType = 0; /* Power supply type. The value 0 indicates that the device is always on. The value 1 indicates power supply through GPIO. */ 174 } 175 } 176 reset { 177 resetType = 0; /* Reset type. The value 0 indicates that reset is dynamically determined, and 1 indicates reset through GPIO. */ 178 gpioId = 2; /* GPIO pin number. */ 179 activeLevel=1; /* Active level. The value 0 indicates low level, and 1 indicates high level. */ 180 resetHoldTime = 30; /* Hold time (ms) after a reset. */ 181 } 182 bootUpTimeout = 30; /* Boot timeout duration (ms). */ 183 bus { 184 busEnable = 1; /* Whether to initialize the bus. The value 1 means to initialize the bus; the value 0 means the opposite. */ 185 busType = 0; /* Bus type. The value 0 indicates SDIO. */ 186 busId = 2; /* Bus number. */ 187 funcNum = [1]; /* SDIO function number. */ 188 timeout = 1000; /* Timeout duration for data read/write. */ 189 blockSize = 512; /* Size of the data block to read or write. */ 190 } 191 } 192 } 193 ``` 194 - Component configuration 195 196 Add a configuration file **wlan_chip_.hcs** for each chip, for example, **wlan_chip_hi3881.hcs**, and configure related parameters. The following is a configuration example of hi3881. 197 ```text 198 root { 199 wlan_config { 200 hi3881 :& chipList { 201 chipHi3881 :: chipInst { 202 match_attr = "hdf_wlan_chips_hi3881"; /* Attribute used to match the chip. */ 203 chipName = "hi3881"; /* WLAN chip name. */ 204 bus { 205 vendorId = 0x0296; /* Vendor ID. */ 206 deviceId = [0x5347]; /* Device ID. */ 207 } 208 } 209 } 210 } 211 } 212 ``` 213 214#### Initializing and deinitializing the WLAN Chip and WLAN Chip Driver 215 216 - Implement the driver adaptation entry function 217 218 Define a variable of the HdfDriverEntry type based on the chip to hook functions of **Bind()**, **Init()**, and **Release()**. Call **HDF_INIT** to register the driver entry with the HDF. During driver loading, the HDF calls the **Bind** function and then the **Init** function to load the driver. If **Init()** fails to be called, the HDF calls **Release()** to release driver resources. 219 ```c 220 struct HdfDriverEntry g_hdfHisiChipEntry = { 221 .moduleVersion = 1, 222 .Bind = HdfWlanHisiDriverBind, 223 .Init = HdfWlanHisiChipDriverInit, 224 .Release = HdfWlanHisiChipRelease, 225 .moduleName = "HDF_WLAN_CHIPS" 226 }; 227 228 HDF_INIT(g_hdfHisiChipEntry); 229 ``` 230 231 - Register the functions for initializing the chip and chip driver 232 233 Hook the chip initialization function to **InitChip()** and the chip deinitialization function to **DeinitChip()**. 234 235 Hook the chip driver initialization function to **Build()** and the chip driver deinitialization function to **Release()**. 236 237 ```c 238 /* Register WLAN chip functions. */ 239 static int32_t HDFWlanRegHisiDriverFactory(void) 240 { 241 static struct HdfChipDriverFactory tmpFactory = { 0 }; 242 struct HdfChipDriverManager *driverMgr = NULL; 243 driverMgr = HdfWlanGetChipDriverMgr(); 244 if (driverMgr == NULL) { 245 HDF_LOGE("%s fail: driverMgr is NULL!", __func__); 246 return HDF_FAILURE; 247 } 248 tmpFactory.driverName = HI3881_DRIVER_NAME; 249 tmpFactory.GetMaxIFCount = GetHi3881GetMaxIFCount; 250 tmpFactory.InitChip = InitHi3881Chip; 251 tmpFactory.DeinitChip = DeinitHi3881Chip; 252 tmpFactory.Build = BuildHi3881Driver; 253 tmpFactory.Release = ReleaseHi3881Driver; 254 tmpFactory.ReleaseFactory = NULL; 255 if (driverMgr->RegChipDriver(&tmpFactory) != HDF_SUCCESS) { 256 HDF_LOGE("%s fail: driverMgr is NULL!", __func__); 257 return HDF_FAILURE; 258 } 259 260 return HDF_SUCCESS; 261 } 262 263 static int32_t HdfWlanHisiChipDriverInit(struct HdfDeviceObject *device) 264 { 265 (void)device; 266 return HDFWlanRegHisiDriverFactory(); 267 } 268 ``` 269 270 1. Initialize and deinitialize the chip. 271 272 ```c 273 /* Function for initializing the WLAN chip. */ 274 int32_t InitHi3881Chip(struct HdfWlanDevice *device) 275 { 276 uint8_t maxPortCount = 3; 277 int32_t ret = HI_SUCCESS; 278 uint8_t maxRetryCount = 3; 279 if (device == NULL || device->bus == NULL) { 280 HDF_LOGE("%s:NULL ptr!", __func__); 281 return HI_FAIL; 282 } 283 284 do { 285 if (ret != HI_SUCCESS) { 286 if (device->reset != NULL && device->reset->Reset != NULL) { 287 device->reset->Reset(device->reset); 288 } 289 HDF_LOGE("%s:Retry init hi3881!last ret=%d", __func__, ret); 290 } 291 ret = hi_wifi_init(maxPortCount, device->bus); 292 } while (ret != 0 && --maxRetryCount > 0); 293 294 if (ret != 0) { 295 HDF_LOGE("%s:Init hi3881 driver failed!", __func__); 296 return ret; 297 } 298 return HI_SUCCESS; 299 } 300 301 /* Function for deinitializing the WLAN chip. */ 302 int32_t DeinitHi3881Chip(struct HdfWlanDevice *device) 303 { 304 (void)device; 305 int32_t ret = hi_wifi_deinit(); 306 if (ret != 0) { 307 HDF_LOGE("%s:Deinit failed!ret=%d", __func__, ret); 308 } 309 return ret; 310 } 311 ``` 312 313 2. Initialize and deinitialize the chip driver. 314 315 ```c 316 /* Hook the functions of the WLAN chip driver, mac80211, and chip. */ 317 static struct HdfChipDriver *BuildHi3881Driver(struct HdfWlanDevice *device, uint8_t ifIndex) 318 { 319 struct HdfChipDriver *specificDriver = NULL; 320 if (device == NULL) { 321 HDF_LOGE("%s fail: channel is NULL!", __func__); 322 return NULL; 323 } 324 (void)ifIndex; 325 specificDriver = (struct HdfChipDriver *)OsalMemCalloc(sizeof(struct HdfChipDriver)); 326 if (specificDriver == NULL) { 327 HDF_LOGE("%s fail: OsalMemCalloc fail!", __func__); 328 return NULL; 329 } 330 if (memset_s(specificDriver, sizeof(struct HdfChipDriver), 0, sizeof(struct HdfChipDriver)) != EOK) { 331 HDF_LOGE("%s fail: memset_s fail!", __func__); 332 OsalMemFree(specificDriver); 333 return NULL; 334 } 335 336 if (strcpy_s(specificDriver->name, MAX_WIFI_COMPONENT_NAME_LEN, HI3881_DRIVER_NAME) != EOK) { 337 HDF_LOGE("%s fail: strcpy_s fail!", __func__); 338 OsalMemFree(specificDriver); 339 return NULL; 340 } 341 specificDriver->init = Hi3881Init; 342 specificDriver->deinit = Hi3881Deinit; 343 344 HiMac80211Init(specificDriver); 345 346 return specificDriver; 347 } 348 349 /* Release the WLAN chip driver. */ 350 static void ReleaseHi3881Driver(struct HdfChipDriver *chipDriver) 351 { 352 if (chipDriver == NULL) { 353 return; 354 } 355 if (strcmp(chipDriver->name, HI3881_DRIVER_NAME) != 0) { 356 HDF_LOGE("%s:Not my driver!", __func__); 357 return; 358 } 359 OsalMemFree(chipDriver); 360 } 361 362 /* Function for initializing the WLAN chip driver. */ 363 int32_t Hi3881Init(struct HdfChipDriver *chipDriver, struct NetDevice *netDevice) 364 { 365 hi_u16 mode; 366 int32_t ret; 367 nl80211_iftype_uint8 type; 368 (void)chipDriver; 369 HDF_LOGI("%s: start...", __func__); 370 mode = wal_get_vap_mode(); 371 if (mode >= WAL_WIFI_MODE_BUTT) { 372 oam_error_log1(0, 0, "wal_init_drv_netdev:: invalid mode[%d]", mode); 373 return HI_FAIL; 374 } 375 if (mode == WAL_WIFI_MODE_STA) { 376 type = NL80211_IFTYPE_STATION; 377 #ifdef _PRE_WLAN_FEATURE_P2P 378 if (InitNetdev(netDevice, NL80211_IFTYPE_P2P_DEVICE) != HI_SUCCESS) { 379 return HI_FAIL; 380 } 381 #endif 382 } else if (mode == WAL_WIFI_MODE_AP) { 383 type = NL80211_IFTYPE_AP; 384 } else { 385 oam_error_log1(0, 0, "wal_init_drv_netdev:: invalid mode[%d]", mode); 386 return HI_FAIL; 387 } 388 ret = wal_init_drv_wlan_netdev(type, WAL_PHY_MODE_11N, netDevice); 389 if (ret != HI_SUCCESS) { 390 oam_error_log2(0, OAM_SF_ANY, "wal_init_drv_netdev %s failed.l_return:%d\n", netDevice->name, ret); 391 } 392 return ret; 393 } 394 395 /* Function for deinitializing the WLAN chip driver. */ 396 int32_t Hi3881Deinit(struct HdfChipDriver *chipDriver, struct NetDevice *netDevice) 397 { 398 int32_t ret; 399 (void)chipDriver; 400 ret = DeinitNetdev(NL80211_IFTYPE_P2P_DEVICE); 401 if (ret != HI_SUCCESS) { 402 oam_error_log1(0, OAM_SF_ANY, "Hi3881Deinit: DeinitNetdev p2p device fail, ret = %d\n", ret); 403 return ret; 404 } 405 return wal_deinit_drv_wlan_netdev(netDevice); 406 } 407 408 ``` 409 410 During the chip initialization process, call **NetDeviceInit()** to initialize a network device, call **NetDeviceAdd()** to add the network device to a protocol stack, and hook function pointers of **netdev**. 411 412 ```c 413 hi_s32 wal_init_drv_wlan_netdev(nl80211_iftype_uint8 type, wal_phy_mode mode, oal_net_device_stru *netdev) 414 { 415 hi_char *ac_mode_str = NULL; 416 hi_s32 ret; 417 if (oal_unlikely(netdev == HI_NULL)) { 418 oam_error_log0(0, OAM_SF_ANY, "{netdev is null!}"); 419 return HI_ERR_CODE_PTR_NULL; 420 } 421 422 do { 423 /* Initialize the network device. */ 424 ret = wal_init_netdev(type, netdev); 425 if (ret != HI_SUCCESS) { 426 break; 427 } 428 429 ret = wal_init_netif(type, netdev); 430 if (ret != HI_SUCCESS) { 431 break; 432 } 433 ac_mode_str = "11bgn"; 434 if (mode == WAL_PHY_MODE_11G) { 435 ac_mode_str = "11bg"; 436 } else if (mode == WAL_PHY_MODE_11B) { 437 ac_mode_str = "11b"; 438 } 439 440 ret = wal_ioctl_set_mode(netdev, ac_mode_str); 441 } while (false); 442 443 if (ret != HI_SUCCESS) { 444 wal_deinit_wlan_vap(netdev); 445 oal_net_unregister_netdev(netdev); 446 oal_net_clear_netdev(netdev); 447 return HI_FAIL; 448 } 449 450 return HI_SUCCESS; 451 } 452 453 /* Hook function pointers of netdev. For details, see NetDeviceInterFace. */ 454 oal_net_device_ops_stru g_wal_net_dev_ops = 455 { 456 .getStats = wal_netdev_get_stats, 457 .open = wal_netdev_open, 458 .stop = wal_netdev_stop, 459 .xmit = hmac_bridge_vap_xmit, 460 .ioctl = wal_net_device_ioctl, 461 .changeMtu = oal_net_device_change_mtu, 462 .init = oal_net_device_init, 463 .deInit = oal_net_free_netdev, 464 465 ...... 466 467 }; 468 469 hi_s32 wal_init_netif(nl80211_iftype_uint8 type, oal_net_device_stru *netdev, const oal_wireless_dev *wdev) 470 { 471 /* Add the network device to the protocol stack. */ 472 hi_u32 ret = NetDeviceAdd(netdev, (Protocol80211IfType)type); 473 474 ... 475 476 return HI_SUCCESS; 477 } 478 ``` 479 480#### Modifying the MAC Layer Interfaces 481 482After the user-mode message is delivered to the driver, the driver calls the corresponding MAC-layer capability interfaces. 483 484 ```c 485 /* Define the functions for implementing the basic capabilities in the MAC layer for the driver. */ 486 static struct HdfMac80211BaseOps g_baseOps = { 487 .SetMode = WalSetMode, 488 .AddKey = WalAddKey, 489 .DelKey = WalDelKey, 490 .SetDefaultKey = WalSetDefaultKey, 491 .GetDeviceMacAddr = WalGetDeviceMacAddr, 492 .SetMacAddr = WalSetMacAddr, 493 .SetTxPower = WalSetTxPower, 494 .GetValidFreqsWithBand = WalGetValidFreqsWithBand, 495 .GetHwCapability = WalGetHwCapability 496 }; 497 498 /* Define the functions for implementing the STA capabilities in the MAC layer for the driver. */ 499 static struct HdfMac80211STAOps g_staOps = { 500 .Connect = WalConnect, 501 .Disconnect = WalDisconnect, 502 .StartScan = WalStartScan, 503 .AbortScan = WalAbortScan, 504 .SetScanningMacAddress = WalSetScanningMacAddress, 505 }; 506 507 /* Define the functions for implementing the AP capabilities in the MAC layer for the driver. */ 508 static struct HdfMac80211APOps g_apOps = { 509 .ConfigAp = WalConfigAp, 510 .StartAp = WalStartAp, 511 .StopAp = WalStopAp, 512 .ConfigBeacon = WalChangeBeacon, 513 .DelStation = WalDelStation, 514 .SetCountryCode = WalSetCountryCode, 515 .GetAssociatedStasCount = WalGetAssociatedStasCount, 516 .GetAssociatedStasInfo = WalGetAssociatedStasInfo 517 }; 518 519 static struct HdfMac80211P2POps g_p2pOps = { 520 .RemainOnChannel = WalRemainOnChannel, 521 .CancelRemainOnChannel = WalCancelRemainOnChannel, 522 .ProbeReqReport = WalProbeReqReport, 523 .AddIf = WalAddIf, 524 .RemoveIf = WalRemoveIf, 525 .SetApWpsP2pIe = WalSetApWpsP2pIe, 526 .GetDriverFlag = WalGetDriverFlag 527 }; 528 529 /* Initialize mac80211 and hook functions of the chip. */ 530 void HiMac80211Init(struct HdfChipDriver *chipDriver) 531 { 532 if (chipDriver == NULL) { 533 HDF_LOGE("%s:input is NULL!", __func__); 534 return; 535 } 536 chipDriver->ops = &g_baseOps; 537 chipDriver->staOps = &g_staOps; 538 chipDriver->apOps = &g_apOps; 539 chipDriver->p2pOps = &g_p2pOps; 540 } 541 ``` 542 543#### Configuring Event Reporting 544 545The WLAN framework provides interfaces for event reporting. For details, see **hdf_wifi_event.c**. 546 547The following presents how to use **HdfWiFiEventNewSta()** to report information about a newly associated STA. 548 549 ```c 550 hi_u32 oal_cfg80211_new_sta(oal_net_device_stru *net_device, const hi_u8 *mac_addr, hi_u8 addr_len, 551 oal_station_info_stru *station_info, oal_gfp_enum_uint8 en_gfp) 552 { 553 #if (_PRE_OS_VERSION_LINUX == _PRE_OS_VERSION) && !defined(_PRE_HDF_LINUX) 554 cfg80211_new_sta(net_device, mac_addr, station_info, en_gfp); 555 hi_unref_param(addr_len); 556 #elif (_PRE_OS_VERSION_LITEOS == _PRE_OS_VERSION) || defined(_PRE_HDF_LINUX) 557 struct StationInfo info = { 0 }; 558 info.assocReqIes = station_info->assoc_req_ies; 559 info.assocReqIesLen = station_info->assoc_req_ies_len; 560 HdfWifiEventNewSta(net_device, mac_addr, WLAN_MAC_ADDR_LEN, &info); 561 hi_unref_param(en_gfp); 562 hi_unref_param(addr_len); 563 #endif 564 565 return HI_SUCCESS; 566 } 567 ``` 568 569### Debugging and Verification 570 571#### Driver Adaptation Verification 572 573Develop test cases in the WLAN module unit test to verify the basic features of the WLAN module. The following uses Hi3516D V300 standard system as an example. 574 5751. Set up the test environment. 576 577 - Create a **hostapd.conf** file (used to start the AP) and copy the following content to the file: 578 579 ```text 580 interface=wlan0 581 driver=hdf wifi 582 ctrl_interface=udp 583 #Wi-Fi name 584 ssid=test 585 hw_mode=g 586 channel=1 587 ignore_broadcast_ssid=0 588 wpa=2 589 rsn_pairwise=CCMP 590 # Wi-Fi password. 591 wpa_passphrase=12345678 592 ``` 593 594 - Create a **wpa_supplicant.conf** file (used to start the STA) and copy the following content to the file: 595 596 ```text 597 country=GB 598 599 network={ 600 #Hotspot name 601 ssid="test" 602 #Hotspot password 603 psk="12345678" 604 } 605 ``` 606 607 - Create a **dhcpc.sh** file (used to write the IP address allocated by the udhcpc to the device) and copy the following content to the file: 608 609 ```shell 610 #!/system/bin/sh 611 [ -z "$1" ] && echo "Error: should be called from udhcpc" && exit 1 612 613 RESOLV_CONF="/etc/resolv.conf" 614 [ -n "$broadcast" ] && BROADCAST="broadcast $broadcast" 615 [ -n "$subnet" ] && NETMASK="netmask $subnet" 616 617 case "$1" in 618 deconfig) 619 /system/bin/ifconfig $interface 0.0.0.0 620 ;; 621 622 renew|bound) 623 /system/bin/ifconfig $interface $ip $BROADCAST $NETMASK 624 625 if [ -n "$router" ] ; then 626 echo "deleting routers" 627 while busybox route del default gw 0.0.0.0 dev $interface ; do 628 : 629 done 630 631 for i in $router ; do 632 busybox route add default gw $i dev $interface 633 done 634 fi 635 636 echo -n > $RESOLV_CONF 637 [ -n "$domain" ] && echo search $domain >> $RESOLV_CONF 638 for i in $dns ; do 639 echo adding dns $i 640 echo nameserver $i >> $RESOLV_CONF 641 done 642 ;; 643 esac 644 645 exit 0 646 ``` 647 648 - Create the **udhcpd.conf** file and copy the following content to the file. 649 650 In the following example, "opt dns x.x.x.x x.x.x.x" indicates two DNS servers configured. You can configure DNS servers as required. 651 652 ```text 653 start 192.168.12.2 654 end 192.168.12.100 655 interface wlan0 #default: eth0 656 max_leases 20 #default: 254 657 remaining yes #default: yes 658 auto_time 7200 #default: 7200 (2 hours) 659 decline_time 3600 #default: 3600 (1 hour) 660 conflict_time 3600 #default: 3600 (1 hour) 661 offer_time 60 #default: 60 (1 minute) 662 min_lease 60 #defult: 60 663 lease_file /vendor/etc/udhcpd.leases 664 opt dns x.x.x.x x.x.x.x 665 option subnet 255.255.255.0 666 opt router 192.168.12.1 667 ``` 668 669 - Run the following commands to push the files required for the test to the development board: 670 671 ```shell 672 hdc shell "mount -o rw,remount /" 673 timeout /T 1 674 hdc file send dhcpc.sh /system/lib/ 675 hdc shell "chmod 777 /system/lib/dhcpc.sh" 676 hdc file send wpa_supplicant.conf / 677 hdc shell "mount -o rw,remount /vendor" 678 hdc file send hostapd.conf / 679 hdc file send udhcpd.conf /vendor/etc 680 hdc shell "touch /vendor/etc/udhcpd.leases" 681 hdc shell "chmod 777 /vendor/etc/udhcpd.leases" 682 ``` 683 6842. Verify basic Wi-Fi features. 685 686 - Verify basic AP features. 687 688 1. Start the AP on the development board and enable Wi-Fi on the test terminal. For example, choose **Settings** > **WLAN** and turn on Wi-Fi on a mobile phone. 689 690 2. Run the following command in the **cmd** window: 691 ```shell 692 hdc shell 693 hostapd ./hostapd.conf 694 ``` 695 696 3. Run the following commands in another **cmd** window: 697 698 ```shell 699 hdc shell 700 ifconfig wlan0 192.168.12.1 netmask 255.255.255.0 701 busybox udhcpd /vendor/etc/udhcpd.conf 702 ``` 703 704 4. On the mobile phone, select the network named **test** in the available Wi-Fi list and enter the password. (The network name and password are configured in the **hostapd.conf** file.) You can see that network name in the connected Wi-Fi list if the connection is successful. 705 706 5. Ping the test terminal from the development board. 707 708 ```shell 709 busybox ping xxx.xxx.xxx.xxx 710 ``` 711 712 In the command, xxx.xxx.xxx.xxx indicates the IP address of the test terminal. If the test terminal can be pinged, the WLAN driver provides basic features normally. 713 714 - Verify basic STA functions 715 716 1. Start the STA on the development board, and enable the hotspot on the test terminal. (The hotspot name and password are configured in the **hostapd.conf** file. The hotspot name is **test**, and the password is **12345678**.) 717 718 2. Run the following command in the **cmd** window: 719 720 ```shell 721 hdc shell 722 wpa_supplicant -i wlan0 -d -c wpa_supplicant.conf 723 ``` 724 725 3. Run the following commands in another **cmd** window: 726 727 ```shell 728 hdc shell 729 mount -o rw,remount / 730 mount -o rw,remount /vendor 731 busybox udhcpc -i wlan0 -s system/lib/dhcpc.sh 732 ``` 733 The IP addresses of the board and test terminal are displayed if the command is successful. 734 735 4. Ping the test terminal from the development board. 736 737 ```shell 738 busybox ping xxx.xxx.xxx.xxx 739 ``` 740 741 In the command, xxx.xxx.xxx.xxx indicates the IP address of the test terminal. If the test terminal can be pinged, the WLAN driver provides basic features normally. 742 743#### API Usage Example 744 745The WLAN Driver module provides two types of capability interfaces for the upper layer: HDI APIs and HAL APIs. 746- HDI API invocation 747 748 The following uses **GetSupportFeature** as an example to describe the development procedure: 749 750 1. Call **WlanInterfaceGetInstance()** to obtain a WLAN service instance. 751 752 2. Call **Start()** to create a channel between the HAL and the driver and obtain information about the driver network interface card (NIC). 753 754 3. Call **GetSupportFeature()** to obtain the WLAN features supported by the device. 755 756 4. Call **Stop()** to destroy the channel between the HAL and the driver 757 758 5. Call **WlanInterfaceRelease()** to destroy the WLAN service instance. 759 760 Example: 761 ```c 762 #include "v1_0/iwlan_interface.h" 763 #include "wlan_callback_impl.h" 764 #include "wlan_impl.h" 765 766 #define PROTOCOL_80211_IFTYPE_NUM 11 767 #define HDF_SUCCESS 0 768 #define HDF_FAILURE (-1) 769 770 static int32_t hdi_main() 771 { 772 int32_t rc; 773 const char *WLAN_SERVICE_NAME = "wlan_hal_c_service"; 774 static struct IWlanInterface *g_wlanObj = NULL; 775 uint8_t supType[PROTOCOL_80211_IFTYPE_NUM + 1] = {0}; 776 uint32_t supTypeLen = PROTOCOL_80211_IFTYPE_NUM + 1; 777 778 /* Obtain the WLAN service instance. */ 779 g_wlanObj = WlanInterfaceGetInstance(WLAN_SERVICE_NAME); 780 if (g_wlanObj == NULL) 781 { 782 return HDF_FAILURE; 783 } 784 785 /* Create a channel between the HAL and the driver and obtain the driver NIC information. */ 786 rc = g_wlanObj->Start(g_wlanObj); 787 if (rc != HDF_SUCCESS) 788 { 789 return HDF_FAILURE; 790 } 791 792 /* Obtain the WLAN features supported by the device irrespective of the device status (AP, STA, or P2P). 793 rc = g_wlanObj->GetSupportFeature(g_wlanObj, supType, &supTypeLen); 794 if (rc != HDF_SUCCESS) 795 { 796 return HDF_FAILURE; 797 } 798 799 /* Destroy the channel between the HAL and the driver. */ 800 rc = g_wlanObj->Stop(g_wlanObj); 801 if (rc != HDF_SUCCESS) 802 { 803 return HDF_FAILURE; 804 } 805 806 /* Destroy the WLAN service instance. */ 807 rc = WlanInterfaceRelease(g_wlanObj); 808 if (rc != HDF_SUCCESS) 809 { 810 return HDF_FAILURE; 811 } 812 return rc; 813 } 814 815 ``` 816 817 Building: 818 819 1. Add the dependent library file to the build script. 820 821 ```text 822 deps = [ 823 "//drivers/peripheral/wlan/hdi_service:hdi_wlan_service", 824 ] 825 ``` 826 2. Add the dependent header files to the build script. 827 ```text 828 include_dirs = [ 829 "//drivers/peripheral/wlan/interfaces/include", 830 "//drivers/peripheral/wlan/hdi_service", 831 "//drivers/peripheral/wlan/client/include", 832 "//drivers/peripheral/wlan/hal/include", 833 ] 834 ``` 835 3. Run the build script and check whether the build is successful. 836 837- HAL API invocation 838 839 To test a specified interface of the HAL module, perform the following steps: 840 841 1. Call **WifiConstruct()** to create an **IWiFi** instance. 842 843 2. Use the created **IWiFi** instance to call **start()** to create a channel between the HAL and the driver and obtain the driver NIC information. 844 845 3. Call **createFeature()** to create an **apFeature** or **staFeature**. These features can be used to invoke specific APIs. The following uses the **apFeature** instance as an example. 846 847 4. Call related APIs, for example, call **setMacAddress()** to set the MAC address and call **getDeviceMacAddress()** to obtain the device MAC address. 848 849 5. Call **destroyFeature()** to destroy the **apFeature** instance. 850 851 6. Call **Stop()** to destroy the channel between the HAL and the driver. 852 853 7. Call **WifiDestruct()** to destroy the **IWiFi** instance. 854 855 Example: 856 857 ```c 858 #include "wifi_hal.h" 859 #include "wifi_hal_sta_feature.h" 860 #include "wifi_hal_ap_feature.h" 861 #include "wifi_hal_cmd.h" 862 863 #define MAC_LEN 6 864 #define HDF_SUCCESS 0 865 #define HDF_FAILURE (-1) 866 867 static int32_t hal_main() 868 { 869 int32_t ret; 870 struct IWiFi *wifi; 871 struct IWiFiAp *apFeature; 872 873 /* Create an IWiFi instance. */ 874 ret = WifiConstruct(&wifi); 875 if (ret != HDF_SUCCESS || wifi == NULL) { 876 return HDF_FAILURE; 877 } 878 879 /* Create a channel between the HAL and the driver and obtain the driver NIC information. */ 880 ret = wifi->start(wifi); 881 if (ret != HDF_SUCCESS) { 882 return HDF_FAILURE; 883 } 884 885 /* Create an apFeature instance. */ 886 ret = wifi->createFeature(PROTOCOL_80211_IFTYPE_AP, (struct IWiFiBaseFeature **)&apFeature); 887 if (ret != HDF_SUCCESS) { 888 return HDF_FAILURE; 889 } 890 891 /* Obtain the MAC address of the device. */ 892 unsigned char mac[MAC_LEN] = {0}; 893 ret = apFeature->baseFeature.getDeviceMacAddress((struct IWiFiBaseFeature *)apFeature, mac, MAC_LEN); 894 if (ret != HDF_SUCCESS) { 895 return HDF_FAILURE; 896 } 897 898 /* Destroy the apFeature instance. */ 899 ret = wifi->destroyFeature((struct IWiFiBaseFeature *)apFeature); 900 if (ret != HDF_SUCCESS) { 901 return HDF_FAILURE; 902 } 903 904 /* Destroy the channel between the HAL and the driver. */ 905 ret = wifi->stop(wifi); 906 if (ret != HDF_SUCCESS) { 907 return HDF_FAILURE; 908 } 909 910 /* Destroy the IWiFi instance. */ 911 ret = WifiDestruct(&wifi); 912 if (ret != HDF_SUCCESS) { 913 return HDF_FAILURE; 914 } 915 return ret; 916 } 917 ``` 918 Building: 919 1. Add the dependent library file to the build script. 920 921 ```text 922 deps = [ 923 "//drivers/peripheral/wlan/client:wifi_driver_client", 924 "//drivers/peripheral/wlan/hal:wifi_hal", 925 ] 926 ``` 927 928 2. Add the dependent header files to the build script. 929 ```text 930 include_dirs = [ 931 "//drivers/peripheral/wlan/interfaces/include", 932 "//drivers/peripheral/wlan/hdi_service", 933 "//drivers/peripheral/wlan/client/include", 934 "//drivers/peripheral/wlan/hal/include", 935 ] 936 ``` 937 3. Run the build script and check whether the build is successful. 938 939 940 941 942## Reference 943 944- Code repositories: 945 946 **[drivers\_hdf\_core](https://gitee.com/openharmony/drivers_hdf_core)** 947 948 [drivers\_peripheral](https://gitee.com/openharmony/drivers_peripheral) 949 950 [drivers\_interface](https://gitee.com/openharmony/drivers_interface) 951 952- Code paths: 953 954 - Adaptation of WLAN FlowCtl component on LiteOS: **//drivers/hdf_core/adapter/khdf/liteos/model/network/wifi** 955 956 - Adaptation of HDF network model on LiteOS: **//drivers/hdf_core/adapter/khdf/liteos/model/network** 957 958 - Adaptation of WLAN FlowCtl component on Linux, build of the HDF WLAN model, and build of the vendor's WLAN driver: **//drivers/hdf_core/adapter/khdf/linux/model/network/wifi** 959 960 - Core code for implementing the WLAN module: **//drivers/hdf_core/framework/model/network/wifi** 961 962 - External APIs of the WLAN module: **//drivers/hdf_core/framework/include/wifi** 963 964 - HDF network model APIs: **//drivers/hdf_core/framework/include/net** 965 966 - WLAN HDI server implementation: **//drivers/peripheral/wlan** 967
