HelloX网络功能简介及使用和开发指南
HelloX网络功能简介
作为物联网操作系统，网络功能是必备的核心功能之一。按照规划，HelloX实现了两个不同类型的TCP/IP协议栈，一个面向资源受限的嵌入式应用，移植了业界成熟使用的lwIP协议栈。该协议栈简洁明了，功能相对简单，同时专门面向嵌入式领域进行设计和优化，对硬件资源要求很低。另外一个协议栈来自BSD操作系统的协议栈，面向复杂的网络功能丰富的应用场景，比如家庭网关，物联网网关等。为了适应HelloX本身的机制，对BSD协议栈做了一些更改和优化，当然，这是在BSD License允许的范围之内。
目前lwIP协议栈已经成熟稳定运行，面向复杂场景的BSD协议栈正在移植当中。不论采用哪个协议栈，都提供相同的，符合BSD规范的socket API，因此对应用程序来说，协议栈都是透明的。对网卡驱动来说，HelloX本身设计了一套网卡驱动机制，向上屏蔽了不同的IP协议栈之间的差异，因此不论安装的是lwIP协议栈还是BSD协议栈，网卡驱动也都是相同的。
本文对HelloX的网络功能的使用和开发方法，进行简单描述。
在虚拟机上使用网络功能
HelloX V1.78实现了一个PCNet FastEthernet III的网卡驱动程序（对应的网卡控制芯片是AMD的AM79C973）。大部分虚拟机都支持这个网卡，因此有比较广泛的通用性。如果您想试验其它的网卡驱动程序，则需要手工编写一个网卡驱动了。
以Virtual Box虚拟机为例，在虚拟机的“设置”界面中，选择“网络”，这时候会列举出四个网卡。选择“网卡1”，按下图所示进行配置：
注意，“连接方式”选择“桥接网卡”。如果选择其它连接类型，我没有试过，不知道行不行。选择桥接网卡的含义，就是把你的PC机的物理网卡，与虚拟机的“网卡1”，用二层的方式连接了起来。可以想象VirtualBox虚拟了一个以太网交换机，然后把你的电脑的物理网卡，以及虚拟机的网卡1，都连接在了这个虚拟的以太网交换机上。
“界面名称”中，选择你的计算机的物理网卡名称。注意，这个网卡一定是可以用的网卡，最好是你当前上网用的网卡，如果有多个网卡的话。
点开“高级”选项，“控制芯片”一行，按照上图所示进行选择。如果选择其它的控制芯片，就需要编写对应控制芯片的驱动程序了。这是一项很有意思的工作，只要拿到对应芯片的data sheet，基本很快就可以编写出来。如果你能够成功的编写一个网卡驱动，那么恭喜你，应聘任何一家通信类或者嵌入式开发类公司，保准可以通过。有兴趣的朋友可以试试。
点击确定之后，用最新的HelloX版本启动虚拟机即可。注意，缺省情况下，HelloX是通过DHCP方式获取IP地址的，因此与HelloX虚拟机关联的物理网卡，也必须是通过DHCP方式获取IP地址。
当然，如果不是DHCP获取IP地址，也可以手工配置，参考本文下面的network命令部分。
启动虚拟机之后，就可以用network程序，来查看和诊断网络了。比如，可以用iflist命令，来查看获取到的IP地址，用ping命令，来试试网络连接是否正常。下面是在我的计算机上的运行结果：
在这里，简单介绍一下用ping命令诊断网络连接是否正常的方法。这些方法，一般在《网络基础》课程里面都会涉及到。如果要考MCSE，CCNA等证书，这些内容是必考内容。
首先，ping一下环回地址，即127.0.0.1。如果这个地址能ping通，说明TCP/IP协议栈已经正常工作了。如果ping不通，那么就是TCP/IP协议栈都没有起来；
如果环回地址ping通了，再ping一下网络接口的本地地址，也就是网卡地址。在上图中，是10.129.73.4。如果这个地址能够ping通，说明网卡已经被TCP/IP协议栈成功识别和管理。如果这个地址都ping不通，那么说明网卡与IP协议栈没有关联起来；
在本地地址ping通的情况下，再ping缺省网关，在上图中，就是10.129.73.1这个地址。如果这个地址能ping通，说明计算机与路由器之间的通信是正常的。后面如果有网络问题，基本上可以排除是本地计算机问题。如果ping不通，则说明本机与路由器没有正常通信，这时候需要检查网线等物理连接。
在缺省网关ping通的情况下，就可以ping目标服务器了。这时候如果ping通了，就万事大吉了。如果ping不通，那么很可能就是目标服务器的问题，或者是目标服务器与本地路由器之间的问题了。
HelloX的Network程序使用指南
HelloX实现了一个network字符界面应用程序，可以对网络功能进行调试。同时实现了一个抽象的以太网管理框架（Ethernet Framework），实现了一套标准的网络驱动程序接口，屏蔽了不同网络驱动程序之间的差异。这样，不同的硬件，其驱动代码是不同的，但是只要遵循这一套标准的接口规范，就可以无缝挂接到HelloX内核中。
下面简要介绍V1.78版的网络调试程序network，在此基础上，简要介绍一下HelloX的网络驱动程序编写方法。
在字符shell模式下，输入network并回车，即可进入network应用程序。该程序提供了如下一些网络相关命令：
scan命令
该命令用于扫描所有可用的WiFi热点，前提是需要有WLAN硬件支持。该命令会列出所有扫描到的AP热点，如下：
[network-view]scan
Available WiFi list:
-----------------------------
00:BSSID = 20004E9C, RSSI = 76, SSID = 'HelloX_HGW_AP', channel = 1
01:BSSID = 2000508C, RSSI = 15, SSID = 'Celleden_Map1600', channel = 6
如果发现想要连接的热点不在上述列表中，可多执行几次scan命令，很多情况下，一次scan是无法扫描到所有热点的。
注意，要使用scan命令，必须具备WLAN网卡，否则无效。
assoc命令
assoc用于跟某个指定的WiFi热点相关联。Scan只是扫描出一些可用的热点，但是如果需要跟某个热点进行连接，则必须使用assoc命令。如下：
[network-view]assoc HelloX_HGW_AP
上述命令用于连接到名字为“HelloX_HGW_AP”的WiFi热点。注意，该WiFi热点必须是开放的不加密热点，因为上述命令没有指定连接密码。
如果是要连接一个加密的WiFi热点，则可以用/k参数指定连接的密码：
[network-view]assoc HelloX_HGW_AP/k0123456789012
后面是密码。当前只支持WEP加密，因此密码必须是13个字节。
再次说明一下，当前值支持开放不加密的WiFi热点，以及基于WEP加密的WiFi热点，尚不支持WPA加密热点，因此要希望连接成功，必须修改WiFi热点的配置，修改为开放不加密，或者使用WEP加密（密码要设置为13位数字）。
showint命令
该命令用于显示出系统中所有网络接口的统计信息，比如接收报文个数，发送报文个数等。下列是一个简单的输出例子：
[network_view]showint
Statistics information for interface'Marvel_WLAN_Int':
Send frame # : 17
Success send # : 17
Send bytes size : 2946
Receive frame # : 14
Success recv # : 14
Receive bytes size : 1778
各输出字段的含义是自解释的。
iflist命令
能够则列举出系统中所有的网络接口，与其对应的IP地址等信息。与showint不同的是，iflist显示的是网络接口的静态信息（IP地址/掩码/缺省网关等），而showint显示的则是网络接口的动态信息。
下面是iflist的一个输出例子：
[network_view]iflist
--------------------------------------
Inetface name : Ma
IPv4 address : 192.168.43.173
IPv4 mask : 255.255.255.0
IPv4 gateway : 192.168.43.1
Interface MTU : 1500
--------------------------------------
Inetface name : lo
IPv4 address : 127.0.0.1
IPv4 mask : 255.0.0.0
IPv4 gateway : 127.0.0.1
Interface MTU : 0
上面显示了两个网络接口，第一个是WLAN接口，名字只包含了起始的2个字节。
setif命令
setif命令则用于修改接口的静态配置参数。比如，可以通过下列方式，为一个网络接口设置静态的IP地址：
setif Marvel_WLAN_Int /a 192.168.0.100 /m255.255.255.0 /g 192.168.0.1
其中Marvel_WLAN_Int是接口的名字（showint命令可以显示），后面分别是该接口的IP地址/子网掩码/缺省网关。需要注意的是，缺省情况下，接口上是启动DHCP功能的，试图自动获取IP地址。一旦通过上述命令设置静态IP地址，则会同时把该接口上的DHCP功能关闭。
如果要重新打开DHCP功能，则使用如下命令：
setif Marvel_WLAN_Int /d enable
而下列命令，则用于重新启动接口上的DHCP功能：
setif Marvel_WLAN_Int /d enable
重启DHCP功能的目的，是为了立即在接口上发出DHCP请求。缺省情况下，DHCP功能是以指数退避方式来发送DHCP请求报文的，即当接口刚刚使能的时候，会发送DHCP请求，如果没有收到响应，则会在2秒后再发一次，然后是4秒，然后是8秒…以此类推。如果想立即在接口上重新发出DHCP请求，则使用上述命令restart一下即可。
Ping命令
这是最常用的诊断命令，后面直接跟IP地址即可。下面是一个简单的输出例子：
[network_view]ping 192.168.43.1
Ping192.168.43.1 with 64 bytes packet:
[0]Reply from 192.168.43.1,size = 64,time = 40(ms)
[1]Reply from 192.168.43.1,size = 64,time = 180(ms)
[2]Reply from 192.168.43.1,size = 64,time = 180(ms)
pingstatistics: total send = 3,received = 3,0 loss.
如果希望改变缺省的ping报文长度，则可以增加一个参数：
ping 192.168.43.1 /l 1024
上述命令以1024字节为ping报文长度。缺省情况下，会连续ping三个报文，然后结束。如果希望ping更多的报文，则使用下列命令：
ping 192.168.43.1 /c 1000
上述命令可以ping1000个报文。当然，l参数和c参数可以一起使用。
HelloX网络驱动程序编写方法
HelloX实现了一个基于线程轮询机制的以太网驱动程序框架，系统中有一个叫做eth_thread的线程，定时（每隔100ms）轮询网卡驱动程序，试图接收数据帧。如果有合适的数据帧到达，则eth_thread会把这个数据帧递交到IP层处理。
因此，要实现一个以太网驱动程序，需要遵循HelloX的以太网驱动框架，具体来说，就是要实现下列函数：
初始化函数
原型如下，这个函数在以太网驱动程序被加载的时候，会被HelloX调用，用于完成硬件的初始化功能。当然，如果不需要初始化，完全可以写成下列形式：
static BOOLInt_Init(__ETHERNET_INTERFACE*pInt)
{
returnTRUE;
}
硬件的初始化，还可以放在驱动程序的入口函数中，下面会提及。
报文发送函数
原型如下：
static BOOLSendFrame(__ETHERNET_INTERFACE*pInt);
在IP层试图发送报文的时候，以太网驱动框架会调用这个函数。所发送的数据帧已经在IP层面准备好（包括源MAC地址/目的MAC地址等），存放在pInt对象的一个缓冲区中（如下代码），驱动程序只需要发送即可。
typedef struct tag__ETHERNET_INTERFACE{
char ethName[MAX_ETH_NAME_LEN +1];
char ethMac[ETH_MAC_LEN];
char SendBuff[ETH_DEFAULT_MTU];//Sending buffer.
int buffSize;
__ETH_INTERFACE_STATE ifState;
LPVOID pL3Interface;
LPVOID pIntExtension; //Privateinformation.
……
}__ETHERNET_INTERFACE;
其中SendBuff是存放待发送数据帧的缓冲区，buffSize是数据帧的长度，必须小于ETH_DEFAULT_MTU（1500）。
在SendFrame函数中，只需要操作硬件，把SendBuff中的内容送到物理网络上，然后返回即可。
数据帧接收函数
该函数原型如下，会被HelloX的以太网管理框架周期性的调用，以判断是否有数据帧到达：
static structpbuf*RecvFrame(__ETHERNET_INTERFACE* pInt);
在这个函数中，硬件判断有数据帧到达，则需要创建一个pbuf，把数据帧从硬件缓冲区中拷贝到pbuf里面，然后返回这个pbuf。比如下面的实例代码：
static struct pbuf*Marvel_RecvFrame(__ETHERNET_INTERFACE*pInt)
{
struct eth_packet *rx_pkt =&pgmarvel_priv->rx_pkt;
struct pbuf *p, *q;
u16 len =0;
int l = 0;
char *buffer = NULL;
p=NULL;
/*Obtain the size of the packet and put it into the "len"variable. */
len= lbs_rev_pkt();
if(len > 0){
buffer= rx_pkt->data;
/*We allocate a pbuf chain ofpbufs from the pool. */
p= pbuf_alloc(PBUF_RAW, len,PBUF_POOL);
if(p != NULL){
for(q = p; q != NULL; q =q->next){
memcpy((u8_t*)q->payload,(u8_t*)&buffer[l], q->len);
l= l + q->len;
}
}
else
{
}
}
return p;
}
如果硬件判断没有数据帧到达，则只需要返回NULL即可。
特定功能的控制函数
原型如下：
static BOOLEth_Ctrl(__ETHERNET_INTERFACE*pInt,DWORD dwOperation,LPVOID pData);
对于一些以太网的特定控制功能，比如设置MTU大小，修改速率，WiFi的扫描AP/附着AP等，通过这个函数实现。dwOperation指明了需要的操作。
如果没有特殊需要，也可以不需要实现该函数。建议的实现方式是，实现一个只返回TRUE的空函数，比如：
staticBOOLMarvel_Ctrl(__ETHERNET_INTERFACE* pInt,DWORD dwOperation,LPVOID pData)
{
returnTRUE;
}
实现驱动程序入口函数
实现完成上述函数之后，还需要实现一个以太网驱动程序的入口函数，这个入口函数会被HelloX的以太网管理框架调用，用于加载以太网驱动程序。在入口函数中，需要做系列工作：
1． 初始化硬件；
2． 调用AddEthernetInterface，向系统中注册以太网接口。
下面是一个实现实例：
BOOL Marvel_Initialize(LPVOID pData)
{
__ETHERNET_INTERFACE*pMarvelInt = NULL;
char mac[ETH_MAC_LEN];
//初始化硬件，获得硬件的MAC地址，存放在mac数组中。
//调用AddEthernetInterface，注册接口。
pMarvelInt= EthernetManager.AddEthernetInterface(
MARVEL_ETH_NAME, //以太网的名字，任意字符串，不能包含空格。
&mac[0], //MAC地址。
NULL, //初始化函数的参数。
Int_Init, //接口初始化函数，对应上述Int_Init函数
SendFrame, //数据帧发送函数
RecvFrame, //数据帧接收函数
Eth_Ctrl); //控制函数。
if(NULL== pMarvelInt)
{
returnFALSE;
}
returnTRUE;
}
调用AddEthernetInterface的时候，需要使用上面实现的四个操作函数作为参数。调用成功后，会返回一个以太网对象指针，可以保存起来，供后期卸载以太网接口的时候用。
在以太网驱动入口数组中增加一项
最后一步，就是在以太网驱动程序入口函数数组中增加一项，告诉操作系统以太网驱动程序的存在。这样操作系统在初始化的时候，就会调用驱动程序入口函数，加载驱动程序。入口函数数组位于network/ethernet/ethentry.c文件中，下面是一个示例：
__ETHERNET_DRIVER_ENTRYEthernetDriverEntry[]=
{
#ifdef __CFG_NET_MARVELLAN
{Marvel_Initialize,NULL},
#endif
//Please add your ethernet driver's entryhere.
{NULL,NULL}
};
其中Marvel_Initialize是驱动程序入口函数，NULL是入口函数的参数，可以是任意指针。注意，该数组中的第一个网络接口，会被系统自动设置为缺省网络接口，即缺省网关所在的接口，或者HelloX默认路由所在的接口。
这样以太网驱动程序就编写完成了。建议把以太网驱动程序的代码，存放在driver/STM32目录下。重新编译HelloX，即可实现以太网驱动程序的加载。
以太网驱动程序加载成功后，即可食用network程序，进行诊断和调试。如果命令级别的诊断无法发现问题，则可以启用代码级的调试。具体来说，在ethif.h文件中，打开以太网调试开关（__ETH_DEBUG），重新编译并加载运行，即可输出网络运行过程中的更加详细的信息。
HelloX V1.78的代码，可以从github上下载：
github.com/hellox-project/HelloX_OS
有任何问题，欢迎加入QQ群讨论：38467832