!19155 feat:wlan develop guide optimization

Merge pull request !19155 from wangyanzhen/master

zh-cn/device-dev/driver/driver-peripherals-external-des.md

@@ -5,65 +5,71 @@
 
 ### 功能简介
 
-WLAN（Wireless Local Area Network）作为网络设备的一个重要特性，其驱动的开发也是设备开发过程中不可忽略的一部分。
-在OpenHarmony架构中，基于HDF（Hardware Driver Foundation）驱动框架开发的WLAN驱动模块，具备跨操作系统迁移、自适应器件差异、模块化拼装编译等特性。
+无线局域网数据传输是端侧设备不可或缺的一部分，用户可以方便地接入到无线网络进行数据传输和共享，并且在无线网络覆盖区域自由移动，彻底摆脱有线的束缚。基于HDF（Hardware Driver Foundation）驱动框架开发的WLAN驱动，能够屏蔽硬件器件差异，为上层WLAN服务提供稳定的基础能力接口，包括启动扫描、关联/取消关联热点、获取MAC地址、设置MAC地址、获取链路信息等。
 
-### 运作机制
+### 基本概念
+
+开发前，开发者应了解一下WLAN涉及的基本概念：
 
-各WLAN设备厂商的驱动开发人员可根据WLAN模块提供的向下、向上的统一接口适配各自的驱动代码：
+- AP
   
-- 向下统一接口实现的能力包括：建立/关闭WLAN热点、扫描、关联WLAN热点等。
-- 对HDI层向上提供能力包括：设置MAC地址、设置发射功率、获取设备的MAC地址等。
+  无线接入点（Access Point，简称AP），是网络的中心节点，提供无线接入服务。其它无线设备接入后，可以进行数据访问。
 
-WLAN框架如图1所示，其中WLAN Driver模块主要提供启动加载、配置文件解析、提供总线抽象接口等能力，WLAN Chip Driver模块主要提供MAC子层管理实体等。
+- STA
   
-  **图1** WLAN框架
+  站点（Station，简称STA），是无线局域网的最基本组成单元。每一个连接到无线网络中的终端（如笔记本电脑、PDA及其它可以联网的用户设备）都可称为一个站点。
 
-  ![image](figures/WLAN框架.png "WLAN框架")
+- ssid
   
-  WLAN Driver框架如图2所示。
+  无线网络的名称，用来标识一个无线网络，每个无线网络都有自己的ssid。
 
-  **图2** WLAN Driver框架
+- bssid
   
-  ![zh-cn_image_0000001300092359](figures/zh-cn_image_0000001300092359.png)
+  用于标识WLAN中的基本服务集，是唯一的48位MAC地址。
   
-WLAN Driver框架主要由如下模块组成：
+- Scan
 
-1. WLAN Message：该部件为每个服务单独提供业务接口，每个服务也可依赖其他服务形成组合业务接口，此模块支持在用户态、内核态和MCU环境运行，实现部件间的充分解耦。
+  终端设备扫描环境中的无线网络，获取到周围的无线网络信息。包括热点名称（ssid）、工作频带和信号强度等。
 
-2. WLAN Configuration Core：WLAN相关的配置文件进行解析。
+- Associate
 
-3. AP：AP（Access Point）为WLAN终端提供外部接入入口的设备。
+  终端设备指定有效的热点进行连接，成功后即可与AP端数据通信。终端同一时刻只可以和一个AP建立链路。
+
+### 运作机制
 
-4. STA：STA（Station）为接入WLAN系统的终端。
+本文主要介绍基于HDF（Hardware Driver Foundation）驱动框架开发的WLAN功能。WLAN整体框架：
 
-5. Mac80211：定义底层驱动相关的MAC层接口。
+![image](figures/WLAN驱动接口框架图.png "WLAN框架图")
 
-6. Bus：该驱动模块向上提供统一的总线抽象接口。通过向下调用Platform层提供的SDIO接口和封装适配USB、PCIE接口，屏蔽不同内核的差异；通过对不同类型的总线操作进行统一封装，屏蔽不同芯片差异，能够对不同芯片厂商提供完备的总线驱动能力，不同厂商共用此模块接口，从而使厂商的开发更为便捷和统一。
+1. 上层服务基于业务需要调用HDI接口，将用户态消息通过WPA层或HAL层下发至Client层。WPA层接口提供设置加密方式、关联热点、设置信道、隐藏热点等功能，HAL层接口作为WPA接口的补充，提供设置国家码、设置MAC地址、获取信道信息等功能。
    
-7. NetDevice：用于建立专属网络设备，屏蔽不同OS的差异，对WiFi驱动提供统一接口，提供统一的HDF NetDevice数据结构，及其统一管理、注册、去注册能力；对接轻设备及富设备上的Linux的网络设备层。
+2. Message模块将用户态的消息按组件分发至AP、STA等模块。
    
-8. NetBuf：该部件为WLAN驱动提供Linux或者LiteOS原生的网络数据缓冲的统一数据结构的封装以及对网络数据的操作接口的封装。
+3. Hdf_Mac80211定义底层驱动相关的MAC层接口。命令字段下发至Hdf_Mac80211，再通过Bus模块发送到WLAN芯片固件侧。
    
-9. FlowCtl：流控模块，当数据量过大时按照优先级策略处理数据。
+4. Bus模块向上提供统一的总线抽象接口。通过向下调用Platform层提供的SDIO接口和封装适配USB、PCIE接口，屏蔽不同内核的差异；通过对不同类型的总线操作进行统一封装，屏蔽不同芯片差异，能够对不同芯片厂商提供完备的总线驱动能力，不同厂商共用此模块接口，从而使厂商的开发更为便捷和统一。
    
-10. HCC-CFG：WLAN相关参数配置其中包括板级配置、驱动配置、Module配置。
+5. EAPOL（Extensible Authentication Protocol Over LAN），基于局域网的扩展认证协议，主要用于在客户端和设备（接入设备、服务器）之间传送EAP协议报文，以允许EAP协议报文在LAN上传送，完成认证流程，实现设备上线功能。
    
-其中主要模块关系如下：
+6. NetDevice用于建立专属网络设备，屏蔽不同OS的差异，对WiFi驱动提供统一接口，提供统一的HDF NetDevice数据结构，及其统一管理、注册、去注册能力；对接轻设备及富设备上的Linux的网络设备层。
    
-1. WLAN Driver通过HCC-CFG模块和WLAN Configuration Core模块进行配置文件的解析与加载。
+7. NetBuf为WLAN驱动提供Linux或者LiteOS原生的网络数据缓冲的统一数据结构的封装以及对网络数据的操作接口的封装。
    
-2. WLAN Message将用户态的消息按组件分发至AP、STA等模块。
+8. 协议栈与NetDevice模块、NetBuf模块共同协同完成数据流交互。
 
-3. 对于命令字段则下发至Mac80211，再通过Bus模块发送到WLAN芯片固件侧。
+### 约束与限制
 
-4. 协议栈与NetDevice模块、NetBuf模块、FlowCtl模块共同协同完成数据流交互。
+WLAN驱动为上层WLAN服务提供稳定的基础能力接口，HDI接口适用于标准系统，HAL接口适用于小型系统及轻量系统。
 
 ## 开发指导
 
+### 场景介绍
+
+WLAN驱动的主要工作是为上层WLAN服务提供稳定的基础能力接口，保证用户可以方便地接入到无线网络，实现数据传输和共享。不同WLAN模组需要适配OpenHarmony时，请参考如下的接口说明和开发步骤。
+
 ### 接口说明
 
-WLAN模块有三部分对外开放的API接口，如下图所示：
+WLAN模块有三部分对外开放的API接口：
 
 1. 对上层服务提供HDI以及HAL能力接口。
 
@@ -71,12 +77,7 @@ WLAN模块有三部分对外开放的API接口，如下图所示：
 
 3. 驱动直接调用WLAN模块能力接口。
 
-  **图3** WLAN驱动接口框架图
-
-  ![image](figures/WLAN驱动接口框架图.png "WLAN驱动接口框架图")
-
-
-- WLAN驱动模块对上层服务提供的HAL能力接口（适用于小型系统及轻量系统），主要功能有：创建/销毁 IWiFi对象、设置MAC地址等。提供的部分接口说明如表2、表3所示：
+- WLAN驱动模块对上层服务提供的能力接口，主要功能有：创建/销毁IWiFi对象、设置MAC地址、设置发射功率等。以下接口列举的为IDL接口描述生成的对应C语言函数接口，如表1、表2所示。接口声明见idl文件（/drivers/interface/wlan/v1_1/）。
 
     **表1** wifi_hal.h
 
@@ -96,7 +97,7 @@ WLAN模块有三部分对外开放的API接口，如下图所示：
   | int32_t (\*getDeviceMacAddress)(const struct IWiFiBaseFeature \*, unsigned char \*, uint8_t) | 获取设备持久化的MAC地址。 | 
   | int32_t (\*setTxPower)(const struct IWiFiBaseFeature \*, int32_t) | 设置发射功率。 |
 
-- WLAN驱动模块也提供了需要驱动开发人员自行去填充具体实现内容的能力接口，主要功能有：初始化/注销NetDevice、打开/关闭NetDevice、获取NetDevice的状态等。提供的部分接口说明如表4所示：
+- WLAN驱动模块提供了需要驱动开发人员自行去填充具体实现内容的能力接口，主要功能有：初始化/注销NetDevice、打开/关闭NetDevice、获取NetDevice的状态等。提供的部分接口说明如表3所示：
 
     **表3** net_device.h
 
@@ -111,7 +112,7 @@ WLAN模块有三部分对外开放的API接口，如下图所示：
 
 - WLAN驱动模块提供给驱动开发人员可直接调用的能力接口，主要功能有：创建/释放WifiModule、关联/取消关联、申请/释放NetBuf、lwip的pbuf和NetBuf的相互转换等。
 
-  可直接调用的接口如表5、表6和表7所示。
+  可直接调用的接口如表4、表5和表6所示。
 
     **表4** wifi_module.h
 
@@ -142,25 +143,10 @@ WLAN模块有三部分对外开放的API接口，如下图所示：
   | struct pbuf \*NetBuf2Pbuf(const struct NetBuf \*nb) | NetBuf转换为lwip的pbuf。 |
 
 ### 开发步骤
-#### 厂商适配WLAN框架
-
-WLAN驱动基于HDF框架和Platform框架开发，不区分OS和芯片平台，为不同厂商的WLAN模组提供统一的驱动模型，各WLAN模组厂商根据如下开发流程适配WLAN驱动框架。
-
-**开发流程**
-
-1. 配置硬件（例如module、芯片等）相关的参数。wlan_platform.hcs文件中对参数进行配置后，HDF框架会对该文件进行解析，并生成全量配置的结构体对象。
-
-2. 初始化和去初始化WLAN模块相关适配（如WLAN芯片初始化和去初始化、WLAN芯片驱动初始化和去初始化）。
 
-3. 控制流命令下发的适配。
+WLAN驱动基于HDF框架和Platform框架开发，不区分OS和芯片平台，为不同厂商的WLAN模组提供统一的驱动模型，各WLAN模组厂商根据如下开发流程适配WLAN驱动框架。示例以Hi3881WLAN芯片为例。
 
-4. 事件上报的调用。
-
-**开发实例**
-
-本例程提供WLAN模块初始化过程的完整使用流程。示例如下（以Hi3881WLAN芯片为例）：
-
-1. Driver的HCS配置。
+#### 配置Driver的HCS文件
 
    HCS文件配置包括：device相关配置和组件配置。
 
@@ -225,7 +211,8 @@ WLAN驱动基于HDF框架和Platform框架开发，不区分OS和芯片平台，
         }
         ```
 
-2. 驱动适配挂接WLAN芯片的初始化和去初始化、WLAN芯片驱动的初始化和去初始化。
+#### 初始化和去初始化WLAN芯片、WLAN芯片驱动
+
    - 驱动适配入口函数实现
 
      根据各自的芯片定义一个HdfDriverEntry类型的变量，主要实现Bind、Init、Release接口的函数挂接。调用HDF_INIT将驱动入口注册到HDF框架中，在加载驱动时HDF框架会先调用Bind函数，再调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源。
@@ -280,7 +267,8 @@ WLAN驱动基于HDF框架和Platform框架开发，不区分OS和芯片平台，
      }
      ```
 
-   - 芯片的初始化和去初始化
+     1. 芯片的初始化和去初始化
+
       ```c
       /* WLAN芯片的初始化函数 */
       int32_t InitHi3881Chip(struct HdfWlanDevice *device)
@@ -321,7 +309,9 @@ WLAN驱动基于HDF框架和Platform框架开发，不区分OS和芯片平台，
           return ret;
       }
       ```
-   - 芯片驱动的初始化和去初始化
+
+     2. 芯片驱动的初始化和去初始化
+   
       ```c
       /* WLAN芯片驱动挂接以及Mac80211与芯片侧的函数挂接 */
       static struct HdfChipDriver *BuildHi3881Driver(struct HdfWlanDevice *device, uint8_t ifIndex)
@@ -487,7 +477,9 @@ WLAN驱动基于HDF框架和Platform框架开发，不区分OS和芯片平台，
       }
       ```
 
-3. 命令下发绑定，包括具有公共能力的设置MAC地址、设置发射功率等；STA相关的连接、扫描等；AP相关的启动AP、设置国家码等。
+#### 适配MAC层能力接口
+
+   用户态消息下发到驱动后，驱动会调用相应的MAC层能力接口。
 
    ```c
    /* 驱动需要实现的MAC层基本能力的控制接口 */
@@ -548,7 +540,9 @@ WLAN驱动基于HDF框架和Platform框架开发，不区分OS和芯片平台，
    }
    ```
 
-4. 事件上报接口调用，WLAN框架提供了event事件的上报接口，详情见hdf_wifi_event.c，例：调用HdfWiFiEventNewSta AP上报新关联的某个STA的情况。
+#### 适配event事件上报
+   
+   WLAN框架提供了event事件的上报接口，详情见hdf_wifi_event.c，例：调用HdfWiFiEventNewSta AP上报新关联的某个STA的情况。
 
    ```c
    hi_u32 oal_cfg80211_new_sta(oal_net_device_stru *net_device, const hi_u8 *mac_addr, hi_u8 addr_len,
@@ -569,7 +563,10 @@ WLAN驱动基于HDF框架和Platform框架开发，不区分OS和芯片平台，
        return HI_SUCCESS;
    }
    ```
-**调测验证**
+
+### 调测验证
+
+#### 驱动适配验证
 
 驱动开发完成后，在WLAN模块单元测试里面开发自测试用例以及验证WLAN模块基本功能。测试环境采用开发者自测试平台（这里以Hi3516DV300标准系统为例）。
 
@@ -739,7 +736,8 @@ WLAN驱动基于HDF框架和Platform框架开发，不区分OS和芯片平台，
 
         上述xxx.xxx.xxx.xxx为当前测试终端的IP地址，若测试能够ping通测试终端则表示，WLAN驱动基本功能正常。
 
-#### 接口调用
+#### 接口使用实例
+
 WLAN驱动模块向上层提供两种能力接口：HDI接口和HAL接口。
 - HDI接口调用