The Wireless Local Area Network (WLAN) Driver module in OpenHarmony is developed based on the Hardware Driver Foundation (HDF). It features cross-OS porting, self-adaptation to component differences, and modular assembly and build.
The Wireless Local Area Network (WLAN) Driver module in OpenHarmony is developed based on the Hardware Driver Foundation (HDF). It provides cross-OS porting, self-adaptation to component differences, and module assembly and building.
### Working Principles
### Working Principles
...
@@ -44,7 +44,7 @@ The WLAN driver consists of the following modules:
...
@@ -44,7 +44,7 @@ The WLAN driver consists of the following modules:
8. NetBuf: encapsulates the unified data structure of the Linux or LiteOS native network data buffer and the operation interfaces for network data.
8. NetBuf: encapsulates the unified data structure of the Linux or LiteOS native network data buffer and the operation interfaces for network data.
9. FlowCtl: performs flow control.
9. FlowCtl: processes data based on the priority when the data volume is too large.
10. HCC-CFG: configures WLAN parameters, including the board configuration, driver configuration, and module configuration.
10. HCC-CFG: configures WLAN parameters, including the board configuration, driver configuration, and module configuration.
...
@@ -74,20 +74,10 @@ The WLAN module provides the following types of APIs:
...
@@ -74,20 +74,10 @@ The WLAN module provides the following types of APIs:
- The WLAN module provides HDI APIs for upper-layer services (applicable to the standard system). **Table 1** describes the major APIs.
**Table 1** IWlanInterface.idl
| API| Description|
| -------- | -------- |
| CreateFeature([in] int type, [out] struct HdfFeatureInfo ifeature);| Creates an **ifeature** instance.|
| DestroyFeature([in] struct HdfFeatureInfo ifeature);| Destroys an **ifeature** instance.|
| GetPowerMode([in] struct HdfFeatureInfo ifeature, [out] unsigned char mode);| Obtains the power mode.|
| SetPowerMode([in] struct HdfFeatureInfo ifeature, [in] unsigned char mode);| Sets the power mode.|
- The WLAN module provides HAL APIs for upper-layer services (applicable to small and mini systems). **Table 2** and **Table 3** describe some APIs.
- The WLAN module provides HAL APIs for upper-layer services (applicable to small and mini systems). **Table 2** and **Table 3** describe some APIs.
**Table 2** wifi_hal.h
**Table 1** wifi_hal.h
| API| Description|
| API| Description|
| -------- | -------- |
| -------- | -------- |
...
@@ -96,7 +86,7 @@ The WLAN module provides the following types of APIs:
...
@@ -96,7 +86,7 @@ The WLAN module provides the following types of APIs:
| int32_t (\*start)(struct IWiFi \*)| Creates a channel between the HAL and the driver and obtains the NICs supported by the driver.|
| int32_t (\*start)(struct IWiFi \*)| Creates a channel between the HAL and the driver and obtains the NICs supported by the driver.|
| int32_t (\*stop)(struct IWiFi \*)| Stops the channel between the HAL and the driver.|
| int32_t (\*stop)(struct IWiFi \*)| Stops the channel between the HAL and the driver.|
**Table 3** wifi_hal_base_feature.h
**Table 2** wifi_hal_base_feature.h
| API| Description|
| API| Description|
| -------- | -------- |
| -------- | -------- |
...
@@ -107,387 +97,370 @@ The WLAN module provides the following types of APIs:
...
@@ -107,387 +97,370 @@ The WLAN module provides the following types of APIs:
- The WLAN Driver module also provides APIs that you need to fill in the implementation. **Table 4** describes some APIs.
- The WLAN Driver module also provides APIs that you need to fill in the implementation. **Table 4** describes some APIs.
**Table 4** net_device.h
**Table 3** net_device.h
| API| Description|
| API| Description|
| -------- | -------- |
| -------- | -------- |
| int32_t (\*init)(struct NetDevice \*netDev)| Initializes a network device.|
| int32_t (\*init)(struct NetDevice \*netDev)| Initializes a network device.|
| struct NetDevStats \*(\*getStats)(struct NetDevice \*netDev)| Obtains the state of a network device.|
| struct NetDevStats \*(\*getStats)(struct NetDevice \*netDev)| Obtains the state of a network device.|
| int32_t (\*setMacAddr)(struct NetDevice \*netDev, void \*addr)| Sets the MAC address.|
| int32_t (\*setMacAddr)(struct NetDevice \*netDev, void \*addr)| Sets the MAC address.|
| void (\*deInit)(struct NetDevice \*netDev)| Deinitializes a network device.|
| void (\*deInit)(struct NetDevice \*netDev)| Deinitializes a network device.|
| int32_t (\*open)(struct NetDevice \*netDev)| Opens a network device.|
| int32_t (\*open)(struct NetDevice \*netDev)| Opens a network device.|
| int32_t (\*stop)(struct NetDevice \*netDev)| Stops a network device.|
| int32_t (\*stop)(struct NetDevice \*netDev)| Stops a network device.|
- 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** structure of Lightweight IP (lwIP) and a **NetBuf**.
- 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** structure of Lightweight IP (lwIP) and a **NetBuf**.
Tables 5 to 7 describe the APIs.
Tables 5 to 7 describe the APIs.
**Table 5** wifi_module.h
**Table 4** wifi_module.h
| API| Description|
| API| Description|
| -------- | -------- |
| -------- | -------- |
| struct WifiModule \*WifiModuleCreate(const struct HdfConfigWifiModuleConfig \*config)| Creates a **WifiModule**.|
| struct WifiModule \*WifiModuleCreate(const struct HdfConfigWifiModuleConfig \*config)| Creates a **WifiModule**.|
| void WifiModuleDelete(struct WifiModule \*module)| Deletes a **WifiModule** and releases its data.|
| void WifiModuleDelete(struct WifiModule \*module)| Deletes a **WifiModule** and releases its data.|
| int32_t DelFeature(struct WifiModule \*module, uint16_t featureType)| Deletes a feature from a **WifiModule**.|
| int32_t DelFeature(struct WifiModule \*module, uint16_t featureType)| Deletes a feature from a **WifiModule**.|
| int32_t AddFeature(struct WifiModule \*module, uint16_t featureType, struct WifiFeature \*featureData)| Adds a feature to a **WifiModule**.|
| int32_t AddFeature(struct WifiModule \*module, uint16_t featureType, struct WifiFeature \*featureData)| Adds a feature to a **WifiModule**.|
**Table 6** wifi_mac80211_ops.h
**Table 5** wifi_mac80211_ops.h
| API| Description|
| API| Description|
| -------- | -------- |
| -------- | -------- |
| int32_t (\*startAp)(NetDevice \*netDev)| Starts an AP.|
| int32_t (\*startAp)(NetDevice \*netDev)| Starts an AP.|
| int32_t (\*stopAp)(NetDevice \*netDev)| Stops an AP.|
| int32_t (\*stopAp)(NetDevice \*netDev)| Stops an AP.|
| int32_t (\*connect)(NetDevice \*netDev, WifiConnectParams \*param)| Connects to a hotspot.|
| int32_t (\*connect)(NetDevice \*netDev, WifiConnectParams \*param)| Connects to a hotspot.|
| int32_t (\*disconnect)(NetDevice \*netDev, uint16_t reasonCode)| Disconnects from a hotspot.|
| int32_t (\*disconnect)(NetDevice \*netDev, uint16_t reasonCode)| Disconnects from a hotspot.|
| struct NetBuf \*NetBufAlloc(uint32_t size)| Allocates a **NetBuf**.|
| struct NetBuf \*NetBufAlloc(uint32_t size)| Allocates a **NetBuf**.|
| void NetBufFree(struct NetBuf \*nb) | Releases a **NetBuf**.|
| void NetBufFree(struct NetBuf \*nb) | Releases a **NetBuf**.|
| struct NetBuf \*Pbuf2NetBuf(const struct NetDevice \*netdev, struct pbuf \*lwipBuf)| Converts the **pbuf** structure of lwIP to a **NetBuf**.|
| struct NetBuf \*Pbuf2NetBuf(const struct NetDevice \*netdev, struct pbuf \*lwipBuf)| Converts the **pbuf** structure of lwIP to a **NetBuf**.|
| struct pbuf \*NetBuf2Pbuf(const struct NetBuf \*nb)| Converts a **NetBuf** to the **pbuf** structure of lwIP.|
| struct pbuf \*NetBuf2Pbuf(const struct NetBuf \*nb)| Converts a **NetBuf** to the **pbuf** structure of lwIP.|
### How to Develop
### How to Develop
#### WLAN Framework Adaptation
The WLAN driver module developed based on the HDF and Platform frameworks provides a unified driver model for WLAN modules of different vendors regardless of the OS and system on a chip (SoC).
The WLAN driver framework developed based on the HDF and Platform framework provides a unified driver model regardless of the OS and system on a chip (SoC). When developing your WLAN driver, you need to configure data based on the WLAN driver framework.
**Development Procedure**
1. Configure hardware (such as modules and chips) parameters in the **wlan_platform.hcs** file. This file can be parsed by the APIs in the HDF to generate structure objects with full configuration.
1. Configure hardware (such as modules and chips) parameters in the **wlan_platform.hcs** file. The HDF parses the file to generate structure objects with full configuration.
2. Implement initialization and deinitialization of the WLAN module (such as initialize and deinitialize the WLAN chip and WLAN chip driver).
2. Implement initialization and deinitialization of the WLAN module (such as initialize and deinitialize the WLAN chip and WLAN chip driver).
3. Implement the delivery of control flow commands.
3. Implement the delivery of control flow commands.
4. Implement event reporting.
4. Implement event reporting.
### Development Example
**Development Example**
The following uses the Hi3881 WLAN chip as an example to describe how to initialize a WLAN module.
The following uses the Hi3881 WLAN chip as an example to describe how to initialize a WLAN module.
1. Configure hardware parameters.
1. Configure the HDF configuration source (HCS) for the driver.
```text
The HCS includes device configuration and component configuration.
/* Configure parameters in wlan_platform.hcs based on the hardware you use. The following is an example of WLAN platform configuration. */
hisi :& deviceList {
- Device configuration
device0 :: deviceInst {
deviceInstId = 0;
The configuration file contains the power supply, reset, and bus configuration.
powers {
power0 {
Configuration file path: **vendor/<vendor name>/<device name >/hdf_config/khdf/wifi**
powerSeqDelay = 0; /* Power sequence delay. */
powerType = 1; /* Power supply type. The value 0 indicates that the device is always on. The value 1 indicates power supply through GPIO. */
Configure device parameters in **wlan_platform.hcs** based on the device you use. The following is an example of WLAN platform configuration.
gpioId = 1; /* GPIO pin number. */
```text
activeLevel=1; /* Active level. The value 0 indicates low level, and 1 indicates high level. */
hisi :& deviceList {
device0 :: deviceInst {
deviceInstId = 0;
powers {
power0 {
powerSeqDelay = 0; /* Power sequence delay. */
powerType = 1; /* Power supply type. The value 0 indicates that the device is always on. The value 1 indicates power supply through GPIO. */
gpioId = 1; /* GPIO pin number. */
activeLevel=1; /* Active level. The value 0 indicates low level, and 1 indicates high level. */
}
power1 {
powerSeqDelay = 0; /* Power sequence delay. */
powerType = 0; /* Power supply type. The value 0 indicates that the device is always on. The value 1 indicates power supply through GPIO. */
}
}
}
power1 {
reset {
powerSeqDelay = 0; /* Power sequence delay. */
resetType = 0; /* Reset type. The value 0 indicates that reset is dynamically determined, and 1 indicates reset through GPIO. */
powerType = 0; /* Power supply type. The value 0 indicates that the device is always on. The value 1 indicates power supply through GPIO. */
gpioId = 2; /* GPIO pin number. */
activeLevel=1; /* Active level. The value 0 indicates low level, and 1 indicates high level. */
resetHoldTime = 30; /* Hold time (ms) after a reset. */
busEnable = 1; /* Whether to initialize the bus. The value 1 means to initialize the bus; the value 0 means the opposite. */
busType = 0; /* Bus type. The value 0 indicates SDIO. */
busId = 2; /* Bus number. */
funcNum = [1]; /* SDIO function number. */
timeout = 1000; /* Timeout duration for data read/write. */
blockSize = 512; /* Size of the data block to read or write. */
}
}
}
}
}
```
/* Add the configuration file wlan_chip_<Chip name>.hcs (for example, wlan_chip_hi3881.hcs) for each chip and set parameters. The following uses the Hi3881 chip as an example. */
- Component configuration
root {
wlan_config {
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.
hi3881 :& chipList {
```text
chipHi3881 :: chipInst {
root {
match_attr = "hdf_wlan_chips_hi3881"; /* Attribute used to match the chip. */
wlan_config {
chipName = "hi3881"; /* WLAN chip name. */
hi3881 :& chipList {
bus {
chipHi3881 :: chipInst {
vendorId = 0x0296; /* Vendor ID. */
match_attr = "hdf_wlan_chips_hi3881"; /* Attribute used to match the chip. */
deviceId = [0x5347]; /* Device ID. */
chipName = "hi3881"; /* WLAN chip name. */
bus {
vendorId = 0x0296; /* Vendor ID. */
deviceId = [0x5347]; /* Device ID. */
}
}
}
}
}
}
}
}
}
}
```
```
2. Hook the **init** and **deinit** functions of the WLAN chip and WLAN chip driver.
2. Hook the **init** and **deinit** functions of the WLAN chip and WLAN chip driver.
- Implementing the driver adaptation entry function
```c
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.
#include "hdf_device_desc.h"
```c
#include "hdf_wifi_product.h"
struct HdfDriverEntry g_hdfHisiChipEntry = {
#include "hdf_log.h"
#include "osal_mem.h"
#include "hdf_wlan_chipdriver_manager.h"
#include "securec.h"
#include "wifi_module.h"
#include "hi_wifi_api.h"
#include "hi_types_base.h"
#define HDF_LOG_TAG Hi3881Driver
/* Functions for initializing and deinitializing a WLAN chip. */
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**.
oam_error_log1(0,OAM_SF_ANY,"Hi3881Deinit: DeinitNetdev p2p device fail, ret = %d\n",ret);
returnret;
}
returnwal_deinit_drv_wlan_netdev(netDevice);
}
```
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**.
/* Add the network device to the protocol stack. */
hi_u32 ret = NetDeviceAdd(netdev, (Protocol80211IfType)type);
...
return HI_SUCCESS;
}
```
3. Bind the commands to be delivered, including setting the MAC address and transmit power, implement STA connection and scan, start APs, and setting the country code.
3. Bind the commands to be delivered, including setting the MAC address and transmit power, implement STA connection and scan, start APs, and setting the country code.
...
@@ -579,10 +548,10 @@ The following uses the Hi3881 WLAN chip as an example to describe how to initial
...
@@ -579,10 +548,10 @@ The following uses the Hi3881 WLAN chip as an example to describe how to initial
4. Invoke the event reporting APIs.
4. Invoke the event reporting APIs.
The WLAN framework provides the event reporting APIs. For details, see **hdf_wifi_event.c**.
The WLAN framework provides the event reporting APIs. For details, see **hdf_wifi_event.c**.
For example, call **HdfWiFiEventNewSta AP** to report information about the newly associated STA.
For example, call **HdfWiFiEventNewSta AP** to report information about the newly associated STA.
Develop 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.
Develop 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.
...
@@ -735,48 +706,58 @@ Develop test cases in the WLAN module unit test to verify the basic features of
...
@@ -735,48 +706,58 @@ Develop test cases in the WLAN module unit test to verify the basic features of
4. On the mobile phone, select the network named **test** in the available Wi-Fi list and enter the password.
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 the network name in the connected Wi-Fi list if the connection is successful.
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.
5. Ping the test terminal from the development board.
5. Ping the test terminal from the development board.
```shell
```shell
busybox ping xxx.xxx.xxx.xxx
busybox ping xxx.xxx.xxx.xxx
```
```
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.
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.
- Verify basic STA features.
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**.)
- Verify basic STA features.
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**.
2. Run the following command in the **cmd** window:
2. Run the following command in the **cmd** window:
```shell
```shell
hdc shell
hdc shell
wpa_supplicant -i wlan0 -d-c wpa_supplicant.conf
wpa_supplicant -i wlan0 -d-c wpa_supplicant.conf
```
```
3. Run the following commands in another **cmd** window:
3. Run the following commands in another **cmd** window:
```shell
```shell
hdc shell
hdc shell
mount -o rw,remount /
mount -o rw,remount /
mount -o rw,remount /vendor
mount -o rw,remount /vendor
busybox udhcpc -i wlan0 -s system/lib/dhcpc.sh
busybox udhcpc -i wlan0 -s system/lib/dhcpc.sh
```
```
The IP addresses of the board and test terminal are displayed if the command is successful.
The IP addresses of the board and test terminal are displayed if the command is successful.
4. Ping the test terminal from the development board.
4. Ping the test terminal from the development board.
```shell
```shell
busybox ping xxx.xxx.xxx.xxx
busybox ping xxx.xxx.xxx.xxx
```
```
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.
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.
#### **API Invocation**
The WLAN driver module provides two types of capability interfaces for the upper layer: HDI interface and HAL interface.
3. Verify the unit test cases.
- HDI API invocation
To test a specified interface of the HDI module, perform the following steps:
The following uses **GetSupportFeature** as an example to describe the development procedure:
1. Call **WlanInterfaceGetInstance()** to obtain a WLAN service instance.
1. Call **WlanInterfaceGetInstance()** to obtain a WLAN service instance.
...
@@ -789,23 +770,22 @@ Develop test cases in the WLAN module unit test to verify the basic features of
...
@@ -789,23 +770,22 @@ Develop test cases in the WLAN module unit test to verify the basic features of
5. Call **WlanInterfaceRelease()** to destroy the WLAN service instance.
5. Call **WlanInterfaceRelease()** to destroy the WLAN service instance.
- 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**
- Adaptation of HDF network model on LiteOS:
- Core code for implementing the WLAN module: **//drivers/hdf_core/framework/model/network/wifi**
- External APIs of the WLAN module: **//drivers/hdf_core/framework/include/wifi**
