第二十八章 USB设备模式/USB OTG

28.1. 简介

本章介绍FreeBSD中USB设备模式和USB On-the-Go（USB OTG）的使用。这包括虚拟串行控制台、虚拟网络接口和虚拟USB驱动器。

当在支持USB设备模式或USB OTG的硬件上运行时，就像许多嵌入式板中内置的那样，FreeBSD USB堆栈可以在设备模式（device mode）下运行。设备模式使计算机能够将自己呈现为不同类型的USB设备类别，包括串行端口、网络适配器和大容量存储器，或其组合。像笔记本电脑或台式电脑这样的USB主机能够像物理USB设备一样访问它们。设备模式有时被称为“USB gadget mode（USB小工具模式）”。

硬件可以通过两种基本方式提供设备模式功能：

• 使用单独的“客户端端口”，仅支持设备模式；
• 以及使用USB OTG端口，可以提供设备和主机模式。

对于USB OTG端口，USB堆栈会根据连接到端口的内容自动在主机侧和设备侧之间切换。将USB设备（如记忆棒）连接到端口会导致FreeBSD切换到主机模式。像连接计算机一样连接USB主机会导致FreeBSD切换到设备模式。单用途“客户端端口”始终在设备模式下工作。

FreeBSD向USB主机呈现的内容取决于 hw.USB.template sysctl。一些模板提供单个设备，如串行终端；其他提供多个，可以同时使用。一个例子是模板10，它提供了一个大容量存储设备、一个串行控制台和一个网络接口。有关可用值的列表，请参阅 usb_template(4) 。

请注意，在某些情况下，根据硬件和主机操作系统的不同，主机要注意到配置更改，必须物理断开并重新连接，或者强制以特定于系统的方式重新扫描USB总线。当FreeBSD在主机上运行时，可以使用 usbconfig(8) reset 。如果usb主机已连接到USBOTG插座，则必须在加载 usb_template.ko 后完成此操作。

阅读本章以了解：

• 如何在FreeBSD上设置USB设备模式功能。 • 如何在FreeBSD上配置虚拟串行端口。 • 如何从各种操作系统连接到虚拟串行端口。 • 如何配置FreeBSD以提供虚拟USB网络接口。 • 如何配置FreeBSD以提供虚拟USB存储设备。

28.2. USB虚拟串行端口

28.2.1. 配置USB设备模式串行端口

虚拟串行端口支持由模板3、8和10提供。请注意，模板3适用于Microsoft Windows 10，无需特殊的驱动程序和INF文件。其他主机操作系统使用所有三个模板。必须加载 usb_template(4) 和 umodem(4) 内核模块。

要启用USB设备模式串行端口，请将这些线添加到 /etc/ttys ：

xxxxxxxxxx
ttyU0 "/usr/libexec/getty 3wire" vt100 onifconsole secure
ttyU1 "/usr/libexec/getty 3wire" vt100 onifconsole secure

然后将这些行添加到 /etc/devd.conf 中：

xxxxxxxxxx
notify 100 {
  match "system" "DEVFS";
  match "subsystem" "CDEV";
  match "type" "CREATE";
  match "cdev" "ttyU[0-9]+";
  action "/sbin/init q";
};

如果 devd(8) 已在运行，请重新加载配置：

xxxxxxxxxx
# service devd restart

确保加载了必要的模块，并在引导时设置了正确的模板，方法是将这些行添加到 /boot/loder.conf 中，如果它还不存在，则创建它：

xxxxxxxxxx
umodem_load="YES"
hw.usb.template=3

要在不重新启动的情况下加载模块并设置模板，请使用：

xxxxxxxxxx
# kldload umodem
# sysctl hw.usb.template=3

28.2.2. 从FreeBSD连接到USB设备模式串行端口

要连接到配置为提供USB设备模式串行端口的板，请将USB主机（如笔记本电脑）连接到板的USB OTG或USB客户端端口。在主机上使用 pstat -t 列出终端线路。列表末尾显示了一个USB串行端口，例如“ttyU0”。要打开连接，请使用：

xxxxxxxxxx
# cu -l /dev/ttyU0

按几次 Enter 键后，会出现登录提示。

28.2.3. 从macOS连接到USB设备模式串行端口

要连接到配置为提供USB设备模式串行端口的板，请将USB主机（如笔记本电脑）连接到板的USB OTG或USB客户端端口。要打开连接，请使用：

xxxxxxxxxx
# cu -l /dev/cu.usbmodemFreeBSD1

28.2.4. 从Linux连接到USB设备模式串行端口

要连接到配置为提供USB设备模式串行端口的板，请将USB主机（如笔记本电脑）连接到板的USB OTG或USB客户端端口。要打开连接，请使用：

xxxxxxxxxx
# minicom -D /dev/ttyACM0

28.2.5. 从Microsoft Windows 10连接到USB设备模式串行端口

要连接到配置为提供USB设备模式串行端口的板，请将USB主机（如笔记本电脑）连接到板的USB OTG或USB客户端端口。要打开连接，需要串行终端程序，如 PuTTY 。要检查Windows使用的COM端口名称，请运行设备管理器，展开“Ports（COM&LPT）”。出现一个类似于“USB Serial Device（COM4）”的名称。运行所选的串行终端程序，例如 PuTTY 。在PuTTY对话框中将“Connection type”设置为“Serial”，在“Serial line”对话框中键入从设备管理器获得的COMx，然后单击“Open”。

28.3. USB设备模式网络接口

虚拟网络接口支持由模板1、8和10提供。请注意，它们都不适用于Microsoft Windows。其他主机操作系统使用所有三个模板。必须加载 usb_template(4) 和 if_cdce(4) 内核模块。

确保加载了必要的模块，并在引导时设置了正确的模板，方法是将这些行添加到 /boot/loder.conf 中，如果它还不存在，则创建它：

xxxxxxxxxx
if_cdce_load="YES"
hw.usb.template=1

要在不重新启动的情况下加载模块并设置模板，请使用：

xxxxxxxxxx
# kldload if_cdce
# sysctl hw.usb.template=1

28.4. USB虚拟存储设备

xxxxxxxxxx
cfumass(4)驱动程序是FreeBSD 12.0中首次提供的USB设备模式驱动程序。

大容量存储目标由模板0和10提供。必须加载 usb_template(4) 和 cfumass(4) 内核模块。cfumass(4) 与CTL子系统的接口，与用于iSCSI或光纤通道目标的接口相同。在主机端，USB大容量存储启动器只能访问单个LUN，即LUN 0。

28.4.1. 使用cfumass启动脚本配置USB大容量存储目标

设置只读USB存储目标的最简单方法是使用 cfumass rc脚本。要以这种方式配置它，请将要呈现给USB主机的文件复制到 /var/cfumass 目录中，并将此行添加到 /etc/rc.conf：

xxxxxxxxxx
cfumass_enable="YES"

要配置目标而不重新启动，请运行以下命令：

xxxxxxxxxx
# service cfumass start

与串行和网络功能不同，在 /boot/loader.conf 中不应将模板设置为0或10。这是因为在设置模板之前必须设置LUN。cfumass启动脚本在启动时会自动设置正确的模板编号。

28.4.2. 使用其他方式配置USB大容量存储

本章的其余部分详细描述了如何在不使用 cfumass rc文件的情况下设置目标。例如，如果想要提供可写LUN，这是必要的。

USB大容量存储不需要运行 ctld(8) 守护进程，但如果需要，也可以使用它。这与iSCSI不同。因此，有两种方法可以配置目标：ctladm(8) 或 ctld(8) 。两者都需要加载 cfumass.ko 内核模块。该模块可以手动加载：

xxxxxxxxxx
# kldload cfumass

如果 cfumass.ko 尚未内置到内核中，可以设置 /boot/loader.conf 在引导时加载模块：

xxxxxxxxxx
cfumass_load="YES"

可以在没有 ctld(8) 守护进程的情况下创建LUN：

xxxxxxxxxx
# ctladm create -b block -o file=/data/target0

这将映像文件 /data/target0 的内容作为LUN呈现给USB主机。执行命令之前，文件必须存在。要在系统启动时配置LUN，请将命令添加到 /etc/rc.local 。

ctld(8) 也可用于管理LUN。创建 /etc/ctl.conf ，在 /etc/rc.conf 中添加一行以确保 ctld(8) 在启动时自动启动，然后启动守护进程。

这是一个简单的 /etc/ctl.conf 配置文件的示例。有关选项的完整描述，请参阅 ctl.conf(5) 。

xxxxxxxxxx
target naa.50015178f369f092 {
    lun 0 {
        path /data/target0
        size 4G
    }
}

该示例使用单个LUN创建单个目标。naa.50015178f369f092 是一个由32个随机十六进制数字组成的设备标识符。 path 行定义了备份LUN的文件或zvol的完整路径。在启动 ctld(8) 之前，该文件必须存在。第二行是可选的，指定LUN的大小。

要确保 ctld(8) 守护进程在启动时启动，请在 /etc/rc.conf 中添加以下行：

xxxxxxxxxx
ctld_enable="YES"

要立即启动 ctld(8) ，请运行以下命令：

xxxxxxxxxx
# service ctld start

当 ctld(8) 守护进程启动时，它会读取 /etc/ctl.conf 。如果在守护进程启动后编辑了此文件，请重新加载更改，使其立即生效：

xxxxxxxxxx
# service ctld reload