在 Linux 主机上入门 Xillybus （机器翻译）

2 安装主机驱动程序

2.1 安装 Xillybus 驱动程序的步骤

安装 Linux 内核驱动程序需执行以下步骤：

• 检查是否确实需要安装。如果不需要，则跳过后续步骤（但可能不跳过最后一步，即复制 udev 文件）。

• 检查先决条件（即确认编译器和内核头文件已安装）。

• 解压下载的驱动程序文件（其中包含作为内核模块的驱动程序）。

• 编译内核模块。

• 安装内核模块。

• 安装 udev 文件，以便 Xillybus 设备文件对任意用户（而不仅仅是 root 用户）可访问。

这些步骤通过命令行（“终端”）完成。附录 A 所载之 Linux 快速参考指 南，可供对该界面操作尚不熟悉的用户参阅。

2.2 是否真的需要安装任何东西？

2.2.1 总体说明

大多数 Linux 内核和 Linux 发行版已支持 Xillybus（针对 PCIe 或 AXI），无需额外操作。下面将作进一步说明。

话虽如此，即使 Xillybus 已经得到支持，也值得阅读第 2.7 节关于安装 udev 文件的内 容。

XillyUSB 的驱动程序从 Linux 内核 5.14 版本（2021 年 8 月发布）起已包含在内。

2.2.2 预装驱动程序的 Linux 发行版

大多数 Linux 发行版（例如 Ubuntu 14.04 及更高版本、近期的 Fedora 发行版、Xillinux（仅限 Zynq 和 Cyclone V SoC 平 台））已预装 PCIe/AXI Xillybus 驱动程序（“开箱即用”）。

要快速检查驱动程序是否已安装，可在 shell 提示符下输入以下命令：

$ modinfo xillybus_core

如果驱动程序已安装，则会打印相关信息。否则会显示“modinfo: ERROR: Module xillybus_core not found”。

类似地，检查 XillyUSB 驱动程序的命令为：

$ modinfo xillyusb

XillyUSB 在 Ubuntu 22.04 及更高版本、Fedora 35 及更高版本以及由此衍生出的发行版中无需安装即可正常工作。

注意：如果 Linux 运行在虚拟机内，它将无法在 PCIe 总线上检测到 Xillybus。运行驱动程序的操作系统必须位于裸机之 上。XillyUSB 可能在虚拟机内工作。

第 2.7 节 展示了如何永久更改 Xillybus 设备文件的权限。此更改可使这些文件对任意用户（而不仅仅是 root 用户）可访问。在桌面计算机上使用 Xillybus 时，通常需要此修改。

2.2.3 包含 Xillybus 驱动程序的 Linux 内 核

Xillybus 的驱动程序（针对 PCIe 和 AXI）从内核 3.12 版本起已包含在官方 Linux 内核中。在 3.12 到 3.17 之间的内核版本中，该驱动程 序以“暂存驱动程序”（staging driver）形式包含，这是 Linux 社区完全接受新驱动程序之前的初步阶段。Xillybus 的驱动程序在 3.18 版本中被 接纳为非暂存状态。尽管与编码风格相关的更改较多，但从最早的内核版本（3.12）到当前可用的驱动程序之间，功能上几乎没有差 异。

当加载暂存驱动程序时，内核会在系统日志中发出警告，称该驱动程序的质量未知。对于 Xillybus，可以安全地忽略此警 告。

如前所述，XillyUSB 的驱动程序从 Linux 内核 5.14 版本起已包含在内。

关于作为 Linux 发行版一部分的内核： 即使 Xillybus 的驱动程序是内核源代码的一部分，也只有在内核配置为 包含这些驱动程序时，它们才会被编译。Xillybus 的驱动程序以内核模块形式包含在大多数主流 Linux 发行版中，但每个发行版都有自己选择 内核包含内容的标准。因此，Xillybus 可能并未包含在发行版附带的内核中。

本指南侧重于通过单独编译内核模块来安装驱动程序。这通常是最简单的方法。然而，那些无论如何都要编译自己内核的用 户，可能更倾向于配置内核以包含 Xillybus 的驱动程序。此方法在第 2.9 节讨论。

2.3 检查先决条件

Linux 系统可能缺少编译内核模块所需的基本工具。判断这些工具是否存在的最简单方法是尝试运行它们。例如，在命令提示符下输 入“make coffee”。正确的响应如下：

$ make coffee

make: *** No rule to make target `coffee'. Stop.

尽管这是一个错误，但我们可以看到“make”工具存在。但如果 GNU make 缺失且需要安装，则输出将类似于：

$ make coffee
bash: make: command not found

同样还需要 C 编译器。输入“gcc”以检查编译器是否已安装：

$ gcc
gcc: no input files

此响应表明“gcc”已安装。这里再次出现了错误消息，但并非“command not found”。

除了这两个工具之外，还需要安装内核头文件。检查这些文件是否缺失的常见方式是：当内核编译失败并显示缺少某个头文 件的错误时。

内核模块编译是一项常见任务，因此互联网上针对每种 Linux 发行版都有大量关于如何为编译准备系统的信息。

在 Fedora、RHEL、CentOS 及其他 Red Hat 衍生版上，以下命令很可能能让计算机准备就绪：

# yum install gcc make kernel-devel-$(uname -r)

对于 Ubuntu 及其他基于 Debian 的发行版：

# apt install gcc make linux-headers-$(uname -r)

2.4 解压下载的文件

从 Xillybus 网站下载驱动程序后，切换到下载文件所在的目录。在命令提示符下输入（不包括 $ 符 号）：

$ tar -xzf xillybus.tar.gz

对于 XillyUSB 驱动程序：

$ tar -xzf xillyusb.tar.gz

应该没有响应，只会出现新的命令提示符。

2.5 运行内核模块的编译

切换到内核模块源代码所在的目录。对于 Xillybus 驱动程序：

$ cd xillybus/module

对于 XillyUSB 驱动程序：

$ cd xillyusb/driver

输入“make”以执行模块编译。输出应类似于以下内容：

$ make
make -C /lib/modules/3.10.0/build SUBDIRS=/home/myself/xillybus/module modules
make[1]: Entering directory `/usr/src/kernels/3.10.0'
 CC [M] /home/myself/xillybus/module/xillybus_core.o
 CC [M] /home/myself/xillybus/module/xillybus_pcie.o
 Building modules, stage 2.
 MODPOST 2 modules
 CC     /home/myself/xillybus/module/xillybus_core.mod.o
 LD [M] /home/myself/xillybus/module/xillybus_core.ko
 CC     /home/myself/xillybus/module/xillybus_pcie.mod.o
 LD [M] /home/myself/xillybus/module/xillybus_pcie.ko
make[1]: Leaving directory `/usr/src/kernels/3.10.0'

具体细节可能略有不同，但不应出现任何错误或警告。对于 XillyUSB，仅生成一个模块 xillyusb.ko。

注意：内核模块的编译是专门针对编译时正在运行的内核的。

如果打算使用另一个内核，请输入“make TARGET=kernel-version”，其中“kernel-version”是所需内核版本的名称。该名称出 现在 /lib/modules/ 中。或者，编辑名为“Makefile”的文件中的以下行：

KDIR := /lib/modules/$(TARGET)/build

将 KDIR 的值更改为所需内核头文件的路径。

2.6 安装内核模块

在不切换目录的情况下，将用户切换为 root（例如使用“sudo su”）。然后输入以下命令：

# make install

此命令可能需要几秒钟才能完成，但不应产生任何错误。

如果此操作失败，请将编译生成的 *.ko 文件复制到现有的内核模块子目录中。然后运行 depmod。以下示例展示了如何为 PCIe 驱动程序执行此操作（假设相关内核版本为 3.10.0）：

# cp xillybus_core.ko /lib/modules/3.10.0/kernel/drivers/char/
# cp xillybus_pcie.ko /lib/modules/3.10.0/kernel/drivers/char/

# depmod -a

安装不会立即将模块加载到内核中。如果系统在启动过程中检测到 Xillybus 外设，这将在下次启动时完成。第 2.8 节展示了如何手动加载模 块。

对于 XillyUSB，无需重新启动： 当下次 USB 设备连接到计算机时，模块会自动加载。

2.7 复制 udev 规则文件

默认情况下，Xillybus 设备文件仅对其所有者（即 root）可访问。让这些文件对任意用户可访问是很有意义的，这样可以避 免以 root 身份操作。udev 机制在创建设备文件时通过遵守特定规则来更改文件权限。

如何启用此功能： 停留在同一目录中，并保持 root 用户身份。将 udev 规则文件复制到系统中此类文件的存储 位置（通常是 /etc/udev/rules.d/）。

例如：

# cp 10-xillybus.rules /etc/udev/rules.d/

此文件的内容简单如下：

SUBSYSTEM=="xillybus", MODE="666", OPTIONS="last_rule"

这意味着由 Xillybus 设备驱动程序生成的所有文件都应被赋予权限模式 0666。换句话说，允许所有人读写。

对于 XillyUSB，文件为 10-xillyusb.rules，内容为：

SUBSYSTEM=="xilly*", KERNEL=="xillyusb_*", MODE="0666"

注意，可以更改 udev 文件以实现不同的结果。例如，可以改为更改设备文件的所有者，以便只有特定用户能够访问这些文 件。

2.8 加载和卸载模块

要加载模块（并开始使用 Xillybus），请以 root 身份输入：

# modprobe xillybus_pcie

或者，对于 XillyUSB：

# modprobe xillyusb

这将使 Xillybus 设备文件出现（假设总线上检测到 Xillybus 设备）。

注意，如果系统在启动过程中检测到 Xillybus PCIe/AXI 外设并且驱动程序已按上述方法安装，则通常不需要此操作。如果 XillyUSB 设备在驱动程序已安装的情况下连接到计算机，同样不需要此操作。

要查看内核中的模块列表，请输入“lsmod”。要从内核中移除模块，请输入（对于 PCIe 驱动程序）：

# rmmod xillybus_pcie xillybus_core

这将使设备文件消失。

如果似乎出现了问题，请检查 /var/log/syslog 文件中包含“xillybus”或“xillyusb”的消息（视情况而定）。该日志文件中经常能 发现有价值的线索。也可以通过“dmesg”命令获取相同的日志信息。

如果不存在 /var/log/syslog 日志文件，则可能是 /var/log/messages。也可以尝试命令“journalctl -k”。

2.9 官方 Linux 内核中的 Xillybus 驱动程 序

如前所述，Xillybus 的驱动程序从 v3.12.0 版本起包含在 Linux 内核中。因此，可以编译整个内核，以便该内核支持 Xillybus。这是上述单独安装内核模块的替代方法。

从功能角度来看，涉及内核编译的方法与第 2.3 节至第 2.6 节中描述的步骤产生的结果 相同。

为了将 Xillybus 的驱动程序包含在准备编译的内核中，需要启用一些内核配置选项。有两种方式包含驱动程 序： 要么作为内核模块，要么作为内核映像的一部分。

例如，以下是在内核配置文件 (.config) 中为 PCIe 接口启用 Xillybus 驱动程序的部分：

CONFIG_XILLYBUS=m
CONFIG_XILLYBUS_PCIE=m

“m”表示将驱动程序作为内核模块包含。“y”表示将驱动程序包含在内核映像中。

类似地，对于 XillyUSB（内核 v5.14 及更高版本）：

CONFIG_XILLYUSB=m

更改 .config 的常用方法是使用内核的配置工具： “make config”、“make xconfig”或“make gconfig”。

xconfig 和 gconfig 是图形用户界面工具，更易于使用，因为它们允许搜索字符串“xillybus”以找到 Xillybus 的驱动程序。通过单击复选框即 可启用驱动程序。.config 文件的文本表示有助于验证是否已设置正确的选项。

在内核版本低于 3.18 的系统上，可能需要在尝试启用 Xillybus 之前先启用暂存驱动程序。这会在 .config 文件中生成以下 行：

CONFIG_STAGING=y

在 .config 文件中启用 Xillybus 的驱动程序后，照常运行内核编译。

从内核 5.14 开始，当启用 Xillybus 或 XillyUSB 的驱动程序时，名为 CONFIG_XILLYBUS_CLASS 的选项会自动启用。这是 配置系统依赖规则的结果。因此，不需要手动更改此选项（通常也不可能）。