diff --git a/zh-cn/device-dev/driver/driver-peripherals-external-des.md b/zh-cn/device-dev/driver/driver-peripherals-external-des.md index 24cea68de69b71a33244a6192b5a8609da178d82..d4f00c0f6dcfb0fb995552ad89a2d94f02c2f180 100644 --- a/zh-cn/device-dev/driver/driver-peripherals-external-des.md +++ b/zh-cn/device-dev/driver/driver-peripherals-external-des.md @@ -3,23 +3,39 @@ ## 概述 -WLAN是基于HDF（Hardware Driver Foundation）驱动框架开发的模块，可实现跨操作系统迁移，自适应器件差异，模块化拼装编译等功能。各WLAN厂商驱动开发人员可根据WLAN模块提供的向下统一接口适配各自的驱动代码，实现如下能力：建立/关闭WLAN热点、扫描、关联WLAN热点等；对HDI层向上提供能力如下：设置MAC地址、设置发射功率、获取设备的MAC地址等。WLAN模块框架图如下： +### 功能简介 + +WLAN（Wireless Local Area Network）作为网络设备的一个重要特性，其驱动的开发也是设备开发过程中不可忽略的一部分。 +在OpenHarmony架构中，基于HDF（Hardware Driver Foundation）驱动框架开发的WLAN驱动模块，具备跨操作系统迁移、自适应器件差异、模块化拼装编译等特性。 + +### 运作机制 + +各WLAN设备厂商的驱动开发人员可根据WLAN模块提供的向下、向上的统一接口适配各自的驱动代码： + +- 向下统一接口实现的能力包括：建立/关闭WLAN热点、扫描、关联WLAN热点等。 +- 对HDI层向上提供能力包括：设置MAC地址、设置发射功率、获取设备的MAC地址等。 + +WLAN框架如图1所示，其中WLAN Driver模块主要提供启动加载、配置文件解析、提供总线抽象接口等能力，WLAN Chip Driver模块主要提供MAC子层管理实体等。 **图1** WLAN框架 ![image](figures/WLAN框架.png "WLAN框架") + WLAN Driver框架如图2所示。 + **图2** WLAN Driver框架 ![zh-cn_image_0000001300092359](figures/zh-cn_image_0000001300092359.png) +WLAN Driver框架主要由如下模块组成： + 1. WLAN Message：该部件为每个服务单独提供业务接口，每个服务也可依赖其他服务形成组合业务接口，此模块支持在用户态、内核态和MCU环境运行，实现组件间的充分解耦。 2. WLAN Configuration Core：WLAN相关的配置文件进行解析。 -3. AP：AP为WLAN终端提供外部接入入口的设备。 +3. AP：AP（Access Point）为WLAN终端提供外部接入入口的设备。 -4. STA：STA为接入WLAN系统的终端。 +4. STA：STA（Station）为接入WLAN系统的终端。 5. Mac80211：定义底层驱动相关的MAC层接口。 @@ -33,114 +49,115 @@ WLAN是基于HDF（Hardware Driver Foundation）驱动框架开发的模块， 10. HCC-CFG：WLAN相关参数配置其中包括板级配置、驱动配置、Module配置。 -### WLAN驱动接口架构 +其中主要模块关系如下： -WLAN模块有三部分对外开放的API接口，如下图所示： +1. WLAN Driver通过HCC-CFG模块和WLAN Configuration Core模块进行配置文件的解析与加载。 -1. 对HDI层提供的能力接口。 +2. WLAN Message将用户态的消息按组件分发至AP、STA等模块。 -2. 驱动直接调用WLAN模块能力接口。 +3. 对于命令字段则下发至Mac80211，再通过Bus模块发送到WLAN芯片固件侧。 -3. 提供给各厂商实现的能力接口。 +4. 协议栈与NetDevice模块、NetBuf模块、FlowCtl模块共同协同完成数据流交互。 - **图3** WLAN模块开放能力分布图 +## 开发指导 - ![image](figures/WLAN模块开放能力分布图.png "WLAN模块开放能力分布图") +### 接口说明 +WLAN模块有三部分对外开放的API接口，如下图所示： -## 接口说明 +1. 驱动直接调用WLAN模块能力接口。 -WLAN驱动模块提供给驱动开发人员可直接调用的能力接口，主要功能有：创建/释放WifiModule、关联/取消关联、申请/释放NetBuf、lwip的pbuf和NetBuf的相互转换等。 +2. 提供给各厂商实现的能力接口。 -可直接调用的接口如下： +3. 对HDI层提供的能力接口 - **表1** wifi_module.h -| 接口名称 | 功能描述 | -| -------- | -------- | -| struct WifiModule \*WifiModuleCreate(const struct HdfConfigWifiModuleConfig \*config) | 基于HDF开发WLAN驱动时，创建一个WifiModule。 | -| void WifiModuleDelete(struct WifiModule \*module) | 基于HDF开发WLAN驱动时，删除并释放WifiModule所有数据。 | -| int32_t DelFeature(struct WifiModule \*module, uint16_t featureType) | 基于HDF开发WLAN驱动时，从WifiModule删除一个功能组件。 | -| int32_t AddFeature(struct WifiModule \*module, uint16_t featureType, struct WifiFeature \*featureData) | 基于HDF开发WLAN驱动时，注册一个功能组件到WifiModule。 | + **图3** WLAN驱动接口框架图 - **表2** wifi_mac80211_ops.h + ![image](figures/WLAN驱动接口框架图.png "WLAN驱动接口框架图") -| 接口名称 | 功能描述 | -| -------- | -------- | -| int32_t (\*startAp)(NetDevice \*netDev) | 启动AP。 | -| int32_t (\*stopAp)(NetDevice \*netDev) | 停止AP。 | -| int32_t (\*connect)(NetDevice \*netDev, WifiConnectParams \*param) | 开始关联。 | -| int32_t (\*disconnect)(NetDevice \*netDev, uint16_t reasonCode) | 取消关联。 | +- WLAN驱动模块提供给驱动开发人员可直接调用的能力接口，主要功能有：创建/释放WifiModule、关联/取消关联、申请/释放NetBuf、lwip的pbuf和NetBuf的相互转换等。 - **表3** hdf_netbuf.h + 可直接调用的接口如表1、表2和表3所示。 -| 接口名称 | 功能描述 | -| -------- | -------- | -| static inline void NetBufQueueInit(struct NetBufQueue \*q) | 初始化NetBuf队列。 | -| struct NetBuf \*NetBufAlloc(uint32_t size) | 申请NetBuf。 | -| void NetBufFree(struct NetBuf \*nb) | 释放NetBuf | -| struct NetBuf \*Pbuf2NetBuf(const struct NetDevice \*netdev, struct pbuf \*lwipBuf) | lwip的pbuf转换为NetBuf。 | -| struct pbuf \*NetBuf2Pbuf(const struct NetBuf \*nb) | NetBuf转换为lwip的pbuf。 | + **表1** wifi_module.h -同时WLAN驱动模块也提供了需要驱动开发人员实现的能力接口，主要功能有：初始化/注销NetDevice、打开/关闭NetDevice、获取NetDevice的状态等。提供的部分接口说明如下表所示： + | 接口名称 | 功能描述 | + | -------- | -------- | + | struct WifiModule \*WifiModuleCreate(const struct HdfConfigWifiModuleConfig \*config) | 基于HDF开发WLAN驱动时，创建一个WifiModule。 | + | void WifiModuleDelete(struct WifiModule \*module) | 基于HDF开发WLAN驱动时，删除并释放WifiModule所有数据。 | + | int32_t DelFeature(struct WifiModule \*module, uint16_t featureType) | 基于HDF开发WLAN驱动时，从WifiModule删除一个功能组件。 | + | int32_t AddFeature(struct WifiModule \*module, uint16_t featureType,
 struct WifiFeature \*featureData) | 基于HDF开发WLAN驱动时，注册一个功能组件到WifiModule。 | - **表4** net_device.h + **表2** wifi_mac80211_ops.h -| 接口名称 | 功能描述 | -| -------- | -------- | -| int32_t (\*init)(struct NetDevice \*netDev) | 初始化NetDevice。 | -| struct NetDevStats \*(\*getStats)(struct NetDevice \*netDev) | 获取NetDevice的状态。 | -| int32_t (\*setMacAddr)(struct NetDevice \*netDev, void \*addr) | 设置Mac地址。 | -| void (\*deInit)(struct NetDevice \*netDev) | 注销NetDevice。 | -| int32_t (\*open)(struct NetDevice \*netDev) | 打开NetDevice。 | -| int32_t (\*stop)(struct NetDevice \*netDev) | 关闭NetDevice。 | + | 接口名称 | 功能描述 | + | -------- | -------- | + | int32_t (\*startAp)(NetDevice \*netDev) | 启动AP。 | + | int32_t (\*stopAp)(NetDevice \*netDev) | 停止AP。 | + | int32_t (\*connect)(NetDevice \*netDev, WifiConnectParams \*param) | 开始关联。 | + | int32_t (\*disconnect)(NetDevice \*netDev, uint16_t reasonCode) | 取消关联。 | -WLAN驱动模块对HDI层提供的能力接口，主要功能有：创建/销毁 IWiFi对象、设置MAC地址等。提供的部分接口说明如下表所示： + **表3** hdf_netbuf.h - **表5** wifi_hal.h + | 接口名称 | 功能描述 | + | -------- | -------- | + | static inline void NetBufQueueInit(struct NetBufQueue \*q) | 初始化NetBuf队列。 | + | struct NetBuf \*NetBufAlloc(uint32_t size) | 申请NetBuf。 | + | void NetBufFree(struct NetBuf \*nb) | 释放NetBuf | + | struct NetBuf \*Pbuf2NetBuf(const struct NetDevice \*netdev, struct pbuf \*lwipBuf) | lwip的pbuf转换为NetBuf。 | + | struct pbuf \*NetBuf2Pbuf(const struct NetBuf \*nb) | NetBuf转换为lwip的pbuf。 | -| 接口名称 | 功能描述 | -| -------- | -------- | -| int32_t WifiConstruct(struct IWiFi \*\*wifiInstance) | 创建IWiFi对象，提供IWiFi基本能力。 | -| int32_t WifiDestruct(struct IWiFi \*\*wifiInstance) | 销毁IWiFi对象。 | -| int32_t (\*start)(struct IWiFi \*) | 创建HAL和驱动之间的通道及获取驱动支持的网卡信息。 | -| int32_t (\*stop)(struct IWiFi \*) | 销毁通道。 | +- WLAN驱动模块也提供了需要驱动开发人员自行去填充具体实现内容的能力接口，主要功能有：初始化/注销NetDevice、打开/关闭NetDevice、获取NetDevice的状态等。提供的部分接口说明如表4所示： - **表6** wifi_hal_base_feature.h + **表4** net_device.h -| 接口名称 | 功能描述 | -| -------- | -------- | -| int32_t (\*getFeatureType)(const struct IWiFiBaseFeature \*) | 获取特性的类型。 | -| int32_t (\*setMacAddress)(const struct IWiFiBaseFeature \*, unsigned char \*, uint8_t) | 设置MAC地址。 | -| int32_t (\*getDeviceMacAddress)(const struct IWiFiBaseFeature \*, unsigned char \*, uint8_t) | 获取设备持久化的MAC地址。 | -| int32_t (\*setTxPower)(const struct IWiFiBaseFeature \*, int32_t) | 设置发射功率。 | + | 接口名称 | 功能描述 | + | -------- | -------- | + | int32_t (\*init)(struct NetDevice \*netDev) | 初始化NetDevice。 | + | struct NetDevStats \*(\*getStats)(struct NetDevice \*netDev) | 获取NetDevice的状态。 | + | int32_t (\*setMacAddr)(struct NetDevice \*netDev, void \*addr) | 设置Mac地址。 | + | void (\*deInit)(struct NetDevice \*netDev) | 注销NetDevice。 | + | int32_t (\*open)(struct NetDevice \*netDev) | 打开NetDevice。 | + | int32_t (\*stop)(struct NetDevice \*netDev) | 关闭NetDevice。 | +- WLAN驱动模块对HDI层提供的能力接口，主要功能有：创建/销毁 IWiFi对象、设置MAC地址等。提供的部分接口说明如表5、表6所示： -## 开发步骤 + **表5** wifi_hal.h -WLAN驱动基于HDF框架和PLATFORM框架开发，不区分OS和芯片平台，为不同厂商的WLAN模组提供统一的驱动模型，各WLAN模组厂商根据如下指导适配WLAN驱动框架。 + | 接口名称 | 功能描述 | + | -------- | -------- | + | int32_t WifiConstruct(struct IWiFi \*\*wifiInstance) | 创建IWiFi对象，提供IWiFi基本能力。 | + | int32_t WifiDestruct(struct IWiFi \*\*wifiInstance) | 销毁IWiFi对象。 | + | int32_t (\*start)(struct IWiFi \*) | 创建HAL和驱动之间的通道及获取驱动支持的网卡信息。 | + | int32_t (\*stop)(struct IWiFi \*) | 销毁通道。 | + **表6** wifi_hal_base_feature.h -1. 通过wifi_config.hcs文件，配置硬件参数：module（不同feature）、芯片等。 + | 接口名称 | 功能描述 | + | -------- | -------- | + | int32_t (\*getFeatureType)(const struct IWiFiBaseFeature \*) | 获取特性的类型。 | + | int32_t (\*setMacAddress)(const struct IWiFiBaseFeature \*, unsigned char \*, uint8_t) | 设置MAC地址。 | + | int32_t (\*getDeviceMacAddress)(const struct IWiFiBaseFeature \*, unsigned char \*, uint8_t) | 获取设备持久化的MAC地址。 | + | int32_t (\*setTxPower)(const struct IWiFiBaseFeature \*, int32_t) | 设置发射功率。 | -2. 解析配置文件，生成全量配置的结构体对象。 -3. Module初始化，创建Module。 +### 开发步骤 -4. 挂接chip，初始化chip。 +WLAN驱动基于HDF框架和PLATFORM框架开发，不区分OS和芯片平台，为不同厂商的WLAN模组提供统一的驱动模型，各WLAN模组厂商根据如下指导适配WLAN驱动框架。 -5. 总线初始化。 -6. 上层wpa业务挂接。 +1. 通过wifi_config.hcs文件，配置硬件（例如module、芯片等）相关的参数。此配置文件通过HDF框架中对应的接口解析后，生成全量配置的结构体对象。 +2. Module初始化，创建Module。 -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
-> 以上驱动框架适配步骤一部分已经提供（详细见开发实例），待开发人员实现的部分有：1、根据硬件，修改配置参数；2、适配挂接chip；3、测试自验证。 +3. 挂接Chip，初始化Chip。 +4. 挂接上层WPA（Wi-Fi Protected Access）业务。 -## 开发实例 +### 开发实例 -本例程提供WLAN模块初始化过程的完整使用流程。示例如下（以hi3881WLAN芯片为例）： +本例程提供WLAN模块初始化过程的完整使用流程。示例如下（以Hi3881WLAN芯片为例）： 1、根据硬件，修改配置参数。 @@ -511,3 +528,28 @@ hi_void HiMac80211Init(struct HdfChipDriver *chipDriver) chipDriver->apOps = &g_apOps; } ``` +## 参考 + +- 代码仓库如下： + + [drivers\_hdf\_core](https://gitee.com/openharmony/drivers_hdf_core) + + [drivers\_peripheral](https://gitee.com/openharmony/drivers_peripheral) + +- 代码路径如下： + + WLAN模块流控组件liteos适配：//drivers/hdf_core/adapter/khdf/liteos/model/network/wifi + + HDF网络模型liteos适配：//drivers/hdf_core/adapter/khdf/liteos/model/network + + WLAN模块流控组件Linux适配、HDF WLAN模型及VENDOR WLAN驱动编译： + + //drivers/hdf_core/adapter/khdf/linux/model/network/wifi + + WLAN模块实现核心代码：//drivers/hdf_core/framework/model/network/wifi + + WLAN模块对外接口：//drivers/hdf_core/framework/include/wifi + + HDF网络模型接口：//drivers/hdf_core/framework/include/net + + WLAN HDI接口及具体实现：//drivers/peripheral/wlan diff --git "a/zh-cn/device-dev/driver/figures/WLAN Driver\346\241\206\346\236\266.png" "b/zh-cn/device-dev/driver/figures/WLAN Driver\346\241\206\346\236\266.png" index 6dc1a805d7e9c8f26bce57a352ebb55ed6a0d561..89a927509d9510db05e88cc2c052fe7a421c7c98 100755 Binary files "a/zh-cn/device-dev/driver/figures/WLAN Driver\346\241\206\346\236\266.png" and "b/zh-cn/device-dev/driver/figures/WLAN Driver\346\241\206\346\236\266.png" differ diff --git "a/zh-cn/device-dev/driver/figures/WLAN\346\241\206\346\236\266.png" "b/zh-cn/device-dev/driver/figures/WLAN\346\241\206\346\236\266.png" index 022c2d6f4382a454138f450143babd27b0630871..30fd6bd808679ce27fbf531f99bb08c044e8a5de 100755 Binary files "a/zh-cn/device-dev/driver/figures/WLAN\346\241\206\346\236\266.png" and "b/zh-cn/device-dev/driver/figures/WLAN\346\241\206\346\236\266.png" differ diff --git "a/zh-cn/device-dev/driver/figures/WLAN\346\250\241\345\235\227\345\274\200\346\224\276\350\203\275\345\212\233\345\210\206\345\270\203\345\233\276.png" "b/zh-cn/device-dev/driver/figures/WLAN\346\250\241\345\235\227\345\274\200\346\224\276\350\203\275\345\212\233\345\210\206\345\270\203\345\233\276.png" deleted file mode 100755 index d7af0cdf77c0e2b3abd589d7aa1fafbba40c8b3f..0000000000000000000000000000000000000000 Binary files "a/zh-cn/device-dev/driver/figures/WLAN\346\250\241\345\235\227\345\274\200\346\224\276\350\203\275\345\212\233\345\210\206\345\270\203\345\233\276.png" and /dev/null differ diff --git "a/zh-cn/device-dev/driver/figures/WLAN\351\251\261\345\212\250\346\216\245\345\217\243\346\241\206\346\236\266\345\233\276.png" "b/zh-cn/device-dev/driver/figures/WLAN\351\251\261\345\212\250\346\216\245\345\217\243\346\241\206\346\236\266\345\233\276.png" new file mode 100755 index 0000000000000000000000000000000000000000..c766dbec265f9e98775cbedcd7df651d4fc8dec7 Binary files /dev/null and "b/zh-cn/device-dev/driver/figures/WLAN\351\251\261\345\212\250\346\216\245\345\217\243\346\241\206\346\236\266\345\233\276.png" differ diff --git a/zh-cn/device-dev/driver/figures/zh-cn_image_0000001197807387.png b/zh-cn/device-dev/driver/figures/zh-cn_image_0000001197807387.png index d7af0cdf77c0e2b3abd589d7aa1fafbba40c8b3f..c766dbec265f9e98775cbedcd7df651d4fc8dec7 100644 Binary files a/zh-cn/device-dev/driver/figures/zh-cn_image_0000001197807387.png and b/zh-cn/device-dev/driver/figures/zh-cn_image_0000001197807387.png differ diff --git a/zh-cn/device-dev/driver/figures/zh-cn_image_0000001200092359.png b/zh-cn/device-dev/driver/figures/zh-cn_image_0000001200092359.png index 022c2d6f4382a454138f450143babd27b0630871..30fd6bd808679ce27fbf531f99bb08c044e8a5de 100644 Binary files a/zh-cn/device-dev/driver/figures/zh-cn_image_0000001200092359.png and b/zh-cn/device-dev/driver/figures/zh-cn_image_0000001200092359.png differ diff --git a/zh-cn/device-dev/driver/figures/zh-cn_image_0000001300092359.png b/zh-cn/device-dev/driver/figures/zh-cn_image_0000001300092359.png index 6dc1a805d7e9c8f26bce57a352ebb55ed6a0d561..89a927509d9510db05e88cc2c052fe7a421c7c98 100644 Binary files a/zh-cn/device-dev/driver/figures/zh-cn_image_0000001300092359.png and b/zh-cn/device-dev/driver/figures/zh-cn_image_0000001300092359.png differ