%# -*- coding: utf-8-unix -*-

\chapter{可编程网络平台－操作手册}
\label{app:openbox}

\subsection{FAST简介}

针对近年来关于工业控制网络创新技术、创新网络结构、
时间敏感网络、SDN网络、FPGA硬件加速技术及下一代网络技术的研究需求，
由国防科大与湖南新实共同发起的开源项目
——FAST（FPGA Accelerated Switcing plaTform）于2016年创建。

FAST平台的架构是一种通用多核CPU加FPGA形态的网络处理架构，
该平台架构主要由硬件逻辑和软件逻辑两部分组成，
实现软硬件耦合通信与支持软硬件可编程的网络创新实验系统。
其中硬件包括平台相关的数据IO和FAST硬件逻辑。
软件部分包括通用操作系统与FAST软件逻辑。
FAST软件逻辑包括FAST软件开发环境和FAST UA程序。
在FAST平台，不仅支持FAST的UA编程开发，同时也支持通用APP的运行。

\subsection{设备简介}

OpenBox-S4是一款软硬件全可编程网络实验平台，
基于多核CPU加FPGA异构模型的FAST处理架构实现，
软件在CPU上使用C语言编程，硬件在FPGA芯片上使用Verilog语言编程。
全系统根据FAST架构搭建其软硬件基础运行环境，
内部软硬件用户逻辑支持所有FAST架构开发的应用、
标准的网络协议栈与通用网络应用。
平台软硬件逻辑代码开源免费，支持用户二次开发。

\subsection{设备上电检测}
当我们拿到设备后，并不知道这个设备有没有故障。
所以在使用设备进行实验前，我们尽量简单并全面的对设备进行一次上电检测，
以确认设备是否没有故障。

\subsubsection{设备外部接口及其配件说明}
\begin{enumerate}
  \item 设备外部接口，如下图所示。

  \begin{figure}[!htp]
    \centering
    \includegraphics[width=11cm]{f01}
    \caption{正面外部接口}
    \label{fig:a:ob_f01}
  \end{figure}
  
  \begin{figure}[!htp]
    \centering
    \includegraphics[width=11cm]{f02}
    \caption{反面外部接口}
    \label{fig:a:ob_f02}
  \end{figure}
  
  \item 12V-1A电源线，如下图所示。

  \begin{figure}[!htp]
    \centering
    \includegraphics[width=11cm]{f03}
    \caption{设备电源线}
    \label{fig:a:ob_f03}
  \end{figure}

  \item 串口线，如下图所示。

  \begin{figure}[!htp]
    \centering
    \includegraphics[width=11cm]{f04}
    \caption{设备串口线}
    \label{fig:a:ob_f04}
  \end{figure}

  \item 设备烧录线，如下图所示。

  \begin{figure}[!htp]
    \centering
    \includegraphics[width=11cm]{f05}
    \caption{设备烧录线}
    \label{fig:a:ob_f05}
  \end{figure}

\end{enumerate}

\subsubsection{检测准备}
\begin{enumerate}
  \item 物品准备
  \begin{table}[!htp]
    \small
    \centering
    \caption{以太网帧格式}
    \label{tab:c:wireshark_eth-format}
    \begin{tabular}{|c|c|} \hline
      \heiti 测试项 & \heiti 所需物品 \\ \hline
      上电检测 & 一台设备及电源\\ \hline
      串口检测 & 一台设备及电源、一台电脑、一个micro usb 串口线\\ \hline
      管理网口（MGMT） & 一台设备及电源、一台电脑、一个网线\\ \hline
    \end{tabular}
  \end{table}
\end{enumerate}

\subsubsection{上电检测}
\begin{enumerate}
  \item 连接电源，将电源开关拨到ON（向右）。
  \item 观察电源指示灯变化情况：
  \item 电源开关拨到ON（向右）后，CFG电源指示灯会亮一下；

  \begin{figure}[!htp]
    \centering
    \includegraphics[width=11cm]{f06}
    \caption{电源指示灯（刚接入电源）}
    \label{fig:a:ob_f06}
  \end{figure}
  \item CFG电源指示灯过几秒后就灭了；

  \begin{figure}[!htp]
    \centering
    \includegraphics[width=11cm]{f07}
    \caption{电源指示灯（系统配置）}
    \label{fig:a:ob_f07}
  \end{figure}
  图 7  电源指示灯（系统配置）
  \item 等待15秒左右，RUN电源指示灯常亮。

  \begin{figure}[!htp]
    \centering
    \includegraphics[width=11cm]{f08}
    \caption{电源指示灯（系统运行）}
    \label{fig:a:ob_f08}
  \end{figure}
\end{enumerate}
\subsubsection{串口检测}
\begin{enumerate}
  \item 确保micro usb串口线正确连接到设备上，并且设备已上电。
  \item 确保调试电脑已按照《01\_常用软件的安装使用手册.pdf》
  文档进行了PUTTY串口终端工具的安装。
  \item 确保调试电脑已按照《01\_常用软件的安装使用手册.pdf》
  文档进行了CP2102驱动的安装。
  \item 在电脑的设备管理器，查看设备的COM口数值。
  （如下图，设备成的COM口数值为COM4，不同的电脑显示的COM口数值会不同）
  \item 打开PUTTY工具界面。
  \begin{enumerate}
    \item 先点击左边“category”栏的 “serial”选项；
    \item 在“Serial line to connect to ”栏，填写设备管理器中看到的COM数值；
    \item 在“Speed”栏，填写串口的波特率为“115200”；
    \item 在 “Data bits”栏。填写数据位宽为“8”；
    \item 在“Flow control”栏，选择“None”。
    \item 如下所示，调试电脑的COM数值为COM3，所以“serial line”栏填写为“COM3”。
    （不同电脑的COM数值可能不同，请填写实际的COM数值）

    \begin{figure}[!htp]
      \centering
      \includegraphics[width=11cm]{f09}
      \caption{putty软件串口配置参数}
      \label{fig:a:ob_f09}
    \end{figure}
  \end{enumerate}
\item 点击 “open” ，进入设备系统，则串口测试OK。
\end{enumerate}
\subsubsection{管理网口检测}
\begin{enumerate}
  \item 使用一根网线，将调试电脑与设备的obx0口连接。
  \item 
  \item 设备的eth0网口的默认ip地址为：192.168.50.5，
  所以需要将调试电脑的ip地址设置成与设备eth0网口的ip地址在同一个网段下
  （也就是192.168.50网段）。
  \item 在调试电脑的 控制面板->网络和Internet->网络设备中。
  点击以太网->属性->internet协议版本4（TCP/IPV4），进行ip地址的配置。如下所示。

  \begin{figure}[!htp]
    \centering
    \includegraphics[width=11cm]{f10}
    \caption{配置以太网的ip地址}
    \label{fig:a:ob_f10}
  \end{figure}
  图 10 配置以太网的ip地址
  \item 在调试电脑的 控制面板>系统和安全>Windows Defender 防火墙>自定义设置中。
  关闭调试电脑的防火墙功能。

  \begin{figure}[!htp]
    \centering
    \includegraphics[width=11cm]{f11}
    \caption{关闭防火墙功能}
    \label{fig:a:ob_f11}
  \end{figure}
  \item 在调试电脑的CMD终端下，使用ping命令能正常与eth0网口通讯，
  则说明管理网络检测OK。

  \begin{figure}[!htp]
    \centering
    \includegraphics[width=11cm]{f12}
    \caption{ping 命令测试网络连通性}
    \label{fig:a:ob_f12}
  \end{figure}

\end{enumerate}
\subsection{搭建环境}
OpenBox-S4是一款软硬件全可编程网络实验平台，
根据FAST架构搭建其软硬件基础运行环境，
内部软硬件用户逻辑支持所有FAST架构开发的应用，
是一款专业的网络实验与研究验证平台。
\subsubsection{连接二层交换拓扑}

\begin{figure}[!htp]
  \centering
  \includegraphics[width=11cm]{f13}
  \caption{二层交换连接拓扑示意图}
  \label{fig:a:ob_f13}
\end{figure}

其中PC1的IP地址设置为“192.168.1.20”，PC2的IP地址设置为“192.168.1.21”
\subsubsection{在OpenBox-S4上运行二层交换程序}

\begin{figure}[!htp]
  \centering
  \includegraphics[width=11cm]{f14}
  \caption{二层交换命令启动输出图}
  \label{fig:a:ob_f14}
\end{figure}

在串口登录界面或网络登录界面输入命令：l2switch

\begin{figure}[!htp]
  \centering
  \includegraphics[width=11cm]{f15}
  \caption{二层交换命令运行输出图}
  \label{fig:a:ob_f15}
\end{figure}

\subsubsection{在PC两端进行PING测试}

\begin{figure}[!htp]
  \centering
  \includegraphics[width=11cm]{f16}
  \caption{端主机PING通结果图}
  \label{fig:a:ob_f16}
\end{figure}

\subsection{常用软件安装与使用}
\subsubsection{Wireshark抓包工具的安装使用}
\begin{enumerate}
  \item 安装教程
  \begin{enumerate}
    \item 进入“\\06\_软件包及工具\\抓包工具”目录。

    \begin{figure}[!htp]
      \centering
      \includegraphics[width=11cm]{f17}
      \caption{Wireshark安装包路径}
      \label{fig:a:ob_f17}
    \end{figure}
    \item 鼠标双击Wireshark-win64-3.2.5.exe文件，
    进入到下图中的安装界面。直接点击“agree”进行下一步。

    \begin{figure}[!htp]
      \centering
      \includegraphics[width=11cm]{f18}
      \caption{Wireshark许可协议}
      \label{fig:a:ob_f18}
    \end{figure}
    \item 选择软件的安装路径。

    \begin{figure}[!htp]
      \centering
      \includegraphics[width=11cm]{f19}
      \caption{更改Wireshark安装路径}
      \label{fig:a:ob_f19}
    \end{figure}
    \item 点击 “install”进行安装。

    \begin{figure}[!htp]
      \centering
      \includegraphics[width=11cm]{f20}
      \caption{Wireshark 开始安装}
      \label{fig:a:ob_f20}
    \end{figure}
    \item 弹出Npacp组件安装窗口，点击 “install”进行安装。

    \begin{figure}[!htp]
      \centering
      \includegraphics[width=11cm]{f21}
      \caption{Wireshark 安装Npacp组件}
      \label{fig:a:ob_f21}
    \end{figure}
  \end{enumerate}
  \item 使用教程
  \begin{enumerate}
    \item 捕获网络接口
    \begin{enumerate}
      \item 打开安装好的wireshark，会进入如下所示界面。
      \begin{figure}[!htp]
        \centering
        \includegraphics[width=11cm]{f22}
        \caption{Wireshark启动界面说明}
        \label{fig:a:ob_f22}
      \end{figure}
  
      \item 这里以有线网口为例，则点击选择 “以太网”，
      就可以捕获有线网口的所有数据报文。如下所示。

      \begin{figure}[!htp]
        \centering
        \includegraphics[width=11cm]{f23}
        \caption{以太网接口捕获数据报文情况}
        \label{fig:a:ob_f23}
      \end{figure}
    \end{enumerate}
    \item wireshark 窗口介绍
    wireshark主要分为这几个窗口，如下所示。

    \begin{figure}[!htp]
      \centering
      \includegraphics[width=11cm]{f24}
      \caption{Wireshark窗口说明}
      \label{fig:a:ob_f24}
    \end{figure}
    \begin{enumerate}
      \item Display Filter(显示过滤器)：用于设置过滤条件进行数据包列表过滤。
      \item Packet List Pane(封包列表)：简要地显示捕获到的数据包，
      每个数据包包含编号，时间戳，源地址，目标地址，协议，长度，以及数据包信息。
      不同协议的数据包使用了不同的颜色区分显示。。
      \item Packet Details Pane(封包详细信息)：在数据包列表中选择指定数据包，
      在数据包详细信息中会显示数据包的所有详细信息内容。
      数据包详细信息面板是最重要的，用来查看协议中的每一个字段。
      \item Packet Bytes Pane(16进制数据)：以十六进制和ASCII码的形式显示数据包的内容。
      这里显 示了一个数据包未经处理的原始样子，也就是在链路上传播时的数据形式。
      \item Miscellanous(状态栏)：包含有专家信息、注释、包的数量和Profile。
    \end{enumerate}
    \item 过滤报文
    \begin{enumerate}
      \item 在显示过滤器栏中，输入指定地过滤条件即可过滤报文。
      \item 如过滤ip地址为“192.168.1.1”的报文，
      则输入过滤条件“ip.addr == 192.168.1.1”。如下所示。

      \begin{figure}[!htp]
        \centering
        \includegraphics[width=11cm]{f25}
        \caption{过滤指定ip地址报文}
        \label{fig:a:ob_f24}
      \end{figure}
      \item 如过滤mac地址为“01:00:5e:7f:ff:fa”的报文，
      则输入过滤条件 “eth.addr == 01:00:5e:7f:ff:fa”如下所示。

      \begin{figure}[!htp]
        \centering
        \includegraphics[width=11cm]{f26}
        \caption{过滤指定mac地址报文}
        \label{fig:a:ob_f24}
      \end{figure}
      \item 由于篇幅的原因，wireshark的其他使用，在本文档就不再说明了。
    \end{enumerate}
  \end{enumerate}
\end{enumerate}
\subsubsection{CP2102串口驱动的安装使用}
\begin{enumerate}
  \item 在“06\_软件包及工具/CP2102串口驱动”目录下，
  根据电脑的操作系统选择对应的软件包。
  \item 如以windows~10操作系统的电脑为例，
  则选择 “06\_软件包及工具/CP2102串口驱动/win10版/CP210x\_Windows10\_Driver.zip”。
  如下所示。

  \begin{figure}[!htp]
    \centering
    \includegraphics[width=11cm]{f27}
    \caption{CP2102串口驱动压缩包}
    \label{fig:a:ob_f27}
  \end{figure}
  \item 解压软件包，若根据系统为64位，则双击“CP210xVCPInstaller\_x64.exe”运行安装。

  \begin{figure}[!htp]
    \centering
    \includegraphics[width=11cm]{f28}
    \caption{解压CP2102串口驱动压缩包}
    \label{fig:a:ob_f28}
  \end{figure}
  \item 如下所示，完成安装。

  \begin{figure}[!htp]
    \centering
    \includegraphics[width=11cm]{f29}
    \caption{CP2102串口驱动完成安装}
    \label{fig:a:ob_f29}
  \end{figure}
\end{enumerate}
\subsection{系统更新}
\subsubsection{系统组成}
OpenBox-S4的系统架构为通用多核CPU加FPGA，
使用的是Xilinx公司的ZYNQ系列芯片提供的整体封装解决方案。
在ZYNQ芯片中包含CPU系统与FPGA系统两部分，其内部通过高速总线连接。
在OpenBox-S4的设备中，其管理接口（MGMT）由CPU引出，其他4个标准网口则由FPGA引出。

整个系统的逻辑运行是从SD卡中的几个文件开始，
主要包括：BOOT.bin、devicetree.dtb、uImage和uramdisk.image.gz四个部分。
其中BOOT.bin定义的整个芯片的物理系统构成、连接关系和FPGA的功能逻辑；
devicetree.dtb文件则定义了系统的硬件资源定义，在CPU运行系统内核镜像时，
提供外设硬件及资源定义参数；uImage是CPU运行的系统内核镜像文件，
提供linux的内核运行环境及外设驱动；uramdisk.image.gz是linux系统的根文件系统，
包含内核引导起来后所使用的存储根文件系统、
系统配置信息、系统命令工具和用户命令等。

在所有的OpenBox-S4设备的系统中，BOOT.bin与devicetree.dtb是匹配成套生成的，
uImage和uramdisk.image.gz是所有系统通用匹配使用的。
用户如果要修改芯片系统架构、连接以及硬件逻辑，
则需要重新生成BOOT.bin和devicetree.dtb文件，替换原来系统的这两件文件，
即可重新定义设备的硬件逻辑功能。如果需要重新定义系统内核功能，
则需要重新编译生成uImage文件进行替换。如果是用户软件逻辑或工具命令，
则可随时通过网络、U盘等上传至系统/mnt/openbox/目录即可使用。

\subsubsection{系统更新}
如上节所述，更新系统最多是替换该设备环境中的4个核心文件，
通常用户只修改硬件逻辑就不需要替换uImage和uramdisk.image.gz文件，
如果不调修改原有接口的地址资源配置地址，也无需devicetree.dtb文件，
仅需要更新替换Boot.bin文件即可。此文档主要描述一下，
如何更新整个系统运行环境，即替换系统的4个核心文件。

\begin{enumerate}
  \item 备份系统原有系统核心文件
  通过设备的管理接口连接到用户操作主机，
  通过SCP远程复制的方法将OpenBox-S4的系统备份到用户主机本地保存。
  Windows主机请使用putty配套的pscp命令工具，用法相同。

  \begin{figure}[!htp]
    \centering
    \includegraphics[width=11cm]{f30}
    \caption{下载备份原有系统}
    \label{fig:a:ob_f30}
  \end{figure}
  \item 上传用户新的系统核心文件
  
  将用户修改系统硬件逻辑后生成的BOOT.bin和devicetree.dtb
  文件保存在本地update目录中，
  将备份目录中的uImage和uramdisk.image.gz文件复制到update目录，
  确保update更新目录中包含OpenBox-S4系统运行环境的4个核心文件，
  其中BOOT.bin和devicetree.dtb是用户最新生成的。执行如下命令，
  将更新目录的4个核心文件上传替换原来OpenBox-S4上面的核心文件。

  \begin{figure}[!htp]
    \centering
    \includegraphics[width=11cm]{f31}
    \caption{上传更新用户系统}
    \label{fig:a:ob_f31}
  \end{figure}
  \item 断电后重启设备验证系统
  
  确认更新文件已经上传后，即可关机、断电和重新加电进行测试。

  重新加电进入系统后，使用系统自带工具读取硬件系统版本号。
  如果其版本号读出与你的硬件逻辑定义一致，则说明系统更新成功。
  如果不同说明系统更新没有替换原来的文件，请检查上传操作是否与上述截图一致，
  是否有报错信息。系统自带标准五级流水线版本号为0x2020181108，
  如下图所示，即说明系统更新成功
  （当前运行系统的硬件版本号为用户更新版本号：0x2020191231）。

  \begin{figure}[!htp]
    \centering
    \includegraphics[width=11cm]{f32}
    \caption{读硬件版本号验证}
    \label{fig:a:ob_f32}
  \end{figure}
\end{enumerate}