4 示例主机应用程序
4.1 概述
提供了六个 C 程序，演示如何访问 Xillybus 的设备文件（device file）。这些程序可在 Xillybus 的 Windows 程序包中找到， 该程序包是一个 zip 文件，可从提供驱动程序的同一网页下载。
在该 zip 文件中，“precompiled-demoapps”子目录下包含预编译的可执行文件。
源代码位于“demoapps”子目录中。这些 C 程序面向 Microsoft 的 Visual C++ 编译器，该编译器可作为 Microsoft 的 SDK 的 一部分免费下载。这些程序也可在 Visual Studio 中使用。
也可以使用 Cygwin 运行示例程序（参见第 4.3 节）。MinGW 也可用于 此目的。如果选择这两种工具之一，则应使用适用于 Linux 的源代码，并遵循 在 Linux 主机上入门 Xillybus 中的说明。另请参阅第 4.4 节，了解如何将 /dev/ 前缀替换为 \\\\.\\。
“demoapps”子目录包含以下文件：
-
Makefile – 此文件包含“nmake”实用程序用于编译程序所需的规则。
-
streamread.c – 从文件读取数据，将数据发送到标准输出。
-
streamwrite.c – 从标准输入读取数据，将数据发送到文件。
-
memread.c – 执行寻址（seek）后读取数据。演示如何访问 FPGA 中的存储器接口（memory interface）。
-
memwrite.c – 执行寻址后写入数据。演示如何访问 FPGA 中的存储器接口。
-
fifo.c – 演示用户空间 RAM FIFO 的实现。此程序很少有用，因为设备文件的 RAM 缓冲区可以配置为足以应对几乎所有场景。因此 fifo.c 仅适用于非常高的数据速率，且 RAM 缓冲区需要非常大（例如数吉字节）的情况。
-
winstreamread.c – 从文件读取数据，将数据发送到标准输出。此程序的功能与 streamread.c 相同，但 winstreamread.c 使用并演示 Microsoft 的文件 I/O API 而非标准 API。
所有程序（除 winstreamread.c 外）均采用经典的 Linux 风格编写，尽管它们旨在使用 Microsoft 编译器进行编译。
这些程序的目的是展示正确的编码风格。它们也可作为编写您自己程序的基础。然而，这些程序均不适用于实际应用，尤其 是在高数据速率下性能不佳。有关实现高带宽性能的指导，请参阅第 5 章。
这些程序非常简单，仅演示了访问文件的标准方法。这些方法在 Xillybus Windows 主机应用程序编程指南中详细讨论。因此，此处不再对这些程序进行详细说明。
注意，这些程序使用低级 API，例如 _open()、_read() 和 _write()。避免使用更广为人知的 API（如 fopen()、fread()、fwrite() 等），因为后者依赖于 C 运行时库维护的数据缓冲区。这些数据缓冲区可能导致混淆，特别是与 FPGA 的通信常 常因运行时库而延迟。
4.2 编译
如前所述，尝试示例程序无需编译： Xillybus 的 Windows 程序包包含可在 Windows 计算机上直接运行的文件。但显然，要 对这些程序进行修改，则必须进行编译。
习惯使用 Microsoft Visual Studio 的用户可能更偏好使用该编译器，并且知道如何使用该工具。示例程序是简单的命令提示 符应用程序。
然而，以下指南基于 Microsoft 的软件开发工具包 (SDK) 7.1。这是一个较旧且简单的开发工具包，可免费下载。以下说明基 于该软件，主要是因为完成该任务所需的步骤较少。
下载并安装 Windows SDK 7.1。在“开始菜单”中打开“程序文件”，选择 Microsoft Windows SDK v7.1 > Windows SDK 7.1 Command Prompt。这将打开一个命令提示符窗口，其中已配置了多个用于编译的环境变量。该窗口中的文本以黄色字体显示。
将目录切换到 C 文件所在的位置：
> cd \path\to\demoapps
要编译所有程序，键入“nmake”。预期输出如下：
> nmake
Microsoft (R) Program Maintenance Utility Version 10.00.30319.01
Copyright (C) Microsoft Corporation. All rights reserved.
if not exist "XP32_DEBUG/" mkdir XP32_DEBUG
cl -D_CRT_SECURE_NO_WARNINGS -c -DCRTAPI1=_cdecl -DCRTAPI2=_cdecl -nologo [ ... ]
link /INCREMENTAL:NO /NOLOGO -subsystem:console,5.01 -out:XP32_DEBUG\ [ ... ]
cl -D_CRT_SECURE_NO_WARNINGS -c -DCRTAPI1=_cdecl -DCRTAPI2=_cdecl -nologo [ ... ]
link /INCREMENTAL:NO /NOLOGO -subsystem:console,5.01 -out:XP32_DEBUG\ [ ... ]
cl -D_CRT_SECURE_NO_WARNINGS -c -DCRTAPI1=_cdecl -DCRTAPI2=_cdecl -nologo [ ... ]
link /INCREMENTAL:NO /NOLOGO -subsystem:console,5.01 -out:XP32_DEBUG\ [ ... ]
cl -D_CRT_SECURE_NO_WARNINGS -c -DCRTAPI1=_cdecl -DCRTAPI2=_cdecl -nologo [ ... ]
link /INCREMENTAL:NO /NOLOGO -subsystem:console,5.01 -out:XP32_DEBUG\ [ ... ]
cl -D_CRT_SECURE_NO_WARNINGS -c -DCRTAPI1=_cdecl -DCRTAPI2=_cdecl -nologo [ ... ]
link /INCREMENTAL:NO /NOLOGO -subsystem:console,5.01 -out:XP32_DEBUG\ [ ... ]
cl -D_CRT_SECURE_NO_WARNINGS -c -DCRTAPI1=_cdecl -DCRTAPI2=_cdecl -nologo [ ... ]
link /INCREMENTAL:NO /NOLOGO -subsystem:console,5.01 -out:XP32_DEBUG\ [ ... ]
以“cl”开头的六行是“nmake”请求使用编译器的命令。这些命令可用于分别编译程序，但没有理由这样做，只需使 用“nmake”即可。“link”命令也是如此，它们对目标文件和库执行链接，从而创建可执行文件。
可执行文件（以及目标文件）可以在 XP32_DEBUG 子目录中找到。如有必要，该子目录会在编译过程中创建。顾名思义， 这些文件适用于 32 位 Windows XP。然而，这些可执行文件可在更高版本的 Windows（包括 64 位版本）上运行。
“nmake”实用程序仅编译必要的内容。如果只更改了一个文件，“nmake”将仅请求编译该文件。因此，正常的工作方式是编辑 要编辑的文件，然后使用“nmake”进行重新编译，不会发生不必要的编译。
使用“nmake clean”可以删除先前编译生成的可执行文件。
如前所述，Makefile 包含编译的规则。该文件的语法并不简单，但幸运的是，通常仅凭常识就可以对该文件进行修改。
Makefile 与其所在目录中的文件相关联。因此，可以复制整个目录，然后在此副本内的文件上工作。这两个目录副本互不干扰。
也可以添加一个 C 文件并轻松修改 Makefile，以便“nmake”也编译这个新文件。
4.3 在 Windows 中使用 Linux 工 具
使用 Linux 的用户倾向于使用标准命令行工具来执行简单任务。这些工具在主要使用 Windows 的用户中不太为人所知。主要 原因是 Windows 的命令行工具远不如每台 Linux 计算机上都存在的工具实用。
如前所述，可以按照 在 Linux 主机上入门 Xillybus 中的详细说明执行“Hello world”测试，而不是按照本指南中的说明。要在 Windows 中做到这 一点，需要在计算机上提供一些工具。有几种实现方法：
-
从 Gnuwin32 项目下载并安装两个软件包： Coreutils 和 Util-Linux-NG。 这两个软件包覆盖了“Hello world”测试的需求（也提供了此任务不需要的程序）。注意，即 使使用 Gnuwin32 的安装工具安装了这些软件包，命令提示符的执行路径也不会改变。
-
使用 Xillybus 提供的 Windows 工具： 这些工具可以在 Xillybus 的 Windows 程序包的“unixutils”子目录中找到。 通过这种方式获得的工具是从 Gnuwin32 软件包中挑选出来的，足以满足“Hello world”测试的需要。
-
安装 Cygwin。 选择此方法意味着安装一个完整的系统，该系统提供类似于 Linux 的命令行界面。此类安装可能 包括 GNU C 编译器和其他软件开发工具。对于习惯使用 Linux 命令行的用户，这是推荐的选择。
4.4 与 Linux 的差异
在 Windows 计算机上按照 在 Linux 主机上入门 Xillybus 中描述的方法执行“Hello world”测试时，需要注意一些差异。
最重要的区别是设备文件的路径是 \\.\，而不是 /dev/。例 如，当 Linux 指南提到 /dev/xillybus_read_8 时，Windows 的正确文件名是 \\.\xillybus_read_8。
由于设备文件名包含反斜杠，在某些情况下需要对反斜杠进行转义： 反斜杠本身通常被视为转义字符。因此， 文件名中的每个反斜杠都需要两个反斜杠。换句话说，\\.\ 需要写成 \\\\.\\。 例如，当 Linux 指南提到 /dev/xillybus_read_8 时，在某些情况下应使用文件名 \\\\.\\xillybus_read_8。
但并非总是如此： 当从命令提示符执行程序时，不需要转义字符。命令提示符将反斜杠视为普通字符。
在大多数编程语言中，需要额外的反斜杠。在脚本内部，可能需要额外的反斜杠，这取决于脚本内部如何处理参数。
4.5 Cygwin 的警告消息
在 Cygwin 的命令行界面中需要使用额外的反斜杠。然而，当首次使用 \\\\.\\ 前缀 时，Cygwin 可能会显示如下警告：
$ cat \\\\.\\xillybus_read_8
cygwin warning:
MS-DOS style path detected: \\.\xillybus_read_8
Preferred POSIX equivalent is: //./xillybus_read_8
CYGWIN environment variable option "nodosfilewarning" turns off this warning.
Consult the user's guide for more details about POSIX paths:
\url{http://cygwin.com/cygwin-ug-net/using.html#using-pathnames}
此警告可以忽略。
Xillybus 已在 Cygwin 中经过广泛测试，上述访问设备文件的方法是正确。对于普通文件名，确实最好使用正斜杠。但 Cygwin 不会将 //./ 转换为 \\.\。因此，必须使用反斜杠。
为避免此警告，可以按照警告消息中关于环境变量的建议进行操作。