USB设备仿真框架设计指南——6.DSF核心模拟器

本节描述DSF中包含的核心模拟器。
本节包括以下主题：

DSF USB 2.0总线模拟器（SoftEHCI）

DSF USB设备模拟器（SoftUSBDevice）

DSF USB外部集线器模拟器(SoftUSBHub)

DSF HID协议转换器(SoftHIDProtocolXlator)

---

向微软发送有关此主题的评论

创建日期：2010/9/21

英文原文连接：https://docs.microsoft.com/zh-cn/previous-versions/windows/hardware/dsf/ff538321(v%3dvs.85)

---

DSF USB 2.0总线模拟器（SoftEHCI）

EHCI控制器模拟器（称为SoftEHCI）由较低设备过滤器（SoftEHCI.sys）组成，该过滤器加载到EHCI minport（Usbehci.sys）下面的改良的USB堆栈中。DSF有自己的EHCI minport和USB端口驱动程序版本，它们与DSF库重新链接以拦截它们的硬件访问调用(例如,READ_REGISTER_ULONG 和 IoConnectInterrupt)。这些驱动程序的DSF版本称为Usbport_dsf.sys 和 Usbehci_dsf.sys，并安装为DSF的一部分。

SoftEHCI使用自己的设备标识符（ID），这与任何现有供应商的EHCI控制器不同，并且Usbehci_dsf.sys被安装为该设备ID的功能驱动程序。因此，真实和模拟的EHCI控制器可以共存于单个测试系统上。

软件枚举器Dsfroot.sys安装在DSF运行时，用于枚举SoftEHCI控制器。一个实用程序SoftEHCICfg.exe（也与运行时一起安装）用于向Dsfroot.sys发送命令以安装或删除SoftEHCI控制器。这些命令与USB 2.0控制器的热插拔或意外删除的硬件等效。

下图显示了SoftEHCI公开的对象模型，测试应用程序可以使用。

                          SoftEHCI对象模型的图解说明

SoftEHCI.Ports公开一组SoftEHCIRootHubPort 对象，这些对象使测试应用程序能够将模拟的USB设备连接到控制器的根集线器端口，并从控制器的根集线器端口断开连接。SoftEHCIRootHubPort 还公开了使测试应用程序既能检查又可控制端口状态的属性。

与所有模拟设备一样，SoftEHCI还公开了一个DSFDevice对象（IDSFDevice），您可以在DSF::Devices属性公开的模拟设备树中找到该对象。连接到控制器的根集线器端口的USB设备也可以在DSFDevice::Children属性中枚举。

向微软发送有关此主题的评论

创建日期：2010/9/21

---

DSF USB设备模拟器（SoftUSBDevice）

SoftUSBDevice(ISoftUSBDevice)及其相关对象是每个模拟USB设备的基础。您可以通过生成一个用户模式可执行模块（以任何形式）来创建USB设备模拟器，该模块创建SoftUSBDevice对象并设置其属性以确定设备的配置。SoftUSBDevice对象直接与控制器通信，并且可以通过使用设备模拟器配置的属性值来处理所有标准USB设备请求。下面的图表说明了SoftUSBDevice对象模型。

                                SoftUSBDevice对象模型的图解说明

前一个图中的对象表示USB设备中的描述符层次结构。SoftUSBDevice对象具有由USB 2.0规范定义的设备描述符的属性。SoftUSBDevice(及其相关对象)的许多属性是根据USB 2.0规范定义的描述符字段命名的。

您可以通过设置 SoftUSBDevice::USB属性将设备配置为USB 2.0或USB 1.1。 SoftUSBDevice::DSFDevice属性引用表示USB设备的DSFDevice对象（因为DSF要求所有模拟设备都由DSFDevice对象表示）。当设备模拟器完成其模拟时，它必须调用 SoftUSBDevice::Destroy方法以允许对象清理在其操作期间分配的任何资源。

SoftUSBConfiguration对象（ISoftUSBConfiguration）具有包含配置描述符的属性。SoftUSBDevice::Configurations返回一个集合，该集合包含设备定义的每个配置的SoftUSBConfiguration 对象。设备模拟器必须填充此集合。

SoftUSBDevice::USB1xConfigurations 属性返回一个集合，该集合包含USB 2.0设备以USB 1.x速度连接到外部集线器时使用的一组配置。SoftUSBDevice.DeviceQualifier方法返回一个SoftUSBDeviceQualifier对象（ISoftUSBDeviceQualifier），该对象定义设备的设备限定符描述符。

SoftUSBInterface(ISoftUSBInterface)具有包含接口描述符的属性。SoftUSBInterface::Number和SoftUSBInterface::AlternateSetting 属性保存接口和接口的替代编号。配置的接口集由SoftUSBConfiguration::Interfaces属性返回的集合引用。设备模拟器必须填充此集合。此集合包含配置定义的每个接口替换的SoftUSBInterface对象。在运行时，SoftUSBConfiguration::AlternateForInterface方法返回SoftUSBInterface对象，该对象引用主机当前为给定接口选择的备选对象。

SoftUSBEndpoint对象(ISoftUSBEndpoint)具有包含端点描述符的属性。SoftUSBInterface::Endpoints属性引用表示接口定义的所有端点的SoftUSBEndpoint 对象的集合。设备模拟器必须填充此集合。 SoftUSBDevice::Endpoint0属性引用设备的控制端点。用于表示控制端点的SoftUSBEndpoint对象是由SoftUSDevice对象自动创建的。

SoftUSBEndpoint也是设备模拟器用来控制数据到设备和从设备传输数据的对象。端点可以使用事件驱动或轮询数据传输。对于事件驱动的端点，设备模拟器必须在端点的ISoftUSBEndpointEvents连接点上安装事件接收器。此接口定义了数据从主机移动到端点（OnWriteTransfer）和从端点移动到主机（OnReadTransfer）的事件。设备模拟器可以对ACK、NAK、Err或START这些事件进行判断，以确定主机将接收到的响应。此外，定义了由控制端点使用的事件，这些事件使设备模拟器能够处理非标准设备请求（例如OnDeviceRequest 或OnDeviceRequestComplete），并且在需要的情况下，重写对标准设备请求的处理(OnSetupTransfer)。

对于轮询的端点，SoftUSBEndpoint对象维护传入和传出数据的队列，并且设备模拟器必须周期性地将数据移入或移出这些队列。 SoftUSBEndpoint::QueueINData方法将数据添加到入站队列中。SoftUSBEndpoint::DrainOUTQueue 方法从出站队列中删除数据。对于控制端点，设备模拟器可以使用SoftUSBEndpoint::QueueDeviceRequestResponse方法将响应排队到预期的非标准设备请求。可以对队列进行调整，以获得所保持的最大数据量，以及在入站数据过期之前保持入站数据的时间长度。

SoftUSBString对象(ISoftUSBString) 定义字符串描述符。SoftUSBDevice.Strings 属性引用一组SoftUSBString对象，这些对象包括设备定义的字符串描述符。在其他描述符中指定的字符串描述符索引（例如，SoftUSBDevice.Manufacturer 属性）确定此集合中对应的SoftUSBString对象的索引。

对于特定于设备的描述符数据,SoftUSBConfiguration,SoftUSBInterface和SoftUSBEndpoint 都具有DeviceSpecificDescriptor属性，可以将其设置为一个字节数组，该字节数组将附加到返回到主机的相应描述符上。当设置DeviceSpecificDescriptor时，相应描述符的长度字段被调整以反映附加的设备特定数据。

除了SoftUSBString对象之外，所有对象都具有Context属性，该属性返回DSFPropertyBag对象(IDSFPropertyBag) ，可以使用该对象存储任意数据。此属性使模拟器和测试应用程序可以存储对象的上下文数据。

向微软发送有关此主题的评论

创建日期：2010/9/21

---

DSF USB外部集线器模拟器(SoftUSBHub)

SoftUSBHub对象(ISoftUSBHub) 实现了一个外部USB集线器模拟器。因为USB规范将外部集线器定义为USB设备，所以SoftUSBHub使用SoftUSBDevice(ISoftUSBDevice) 和相关对象，就像任何设备模拟器一样。 SoftUSBHub::SoftUSBDevice 属性引用此对象。下面的图描述了SoftUSBHub对象模型。

                                        SoftUSBHub对象模型的图解说明

 SoftUSBHub::Ports 属性引用一组 SoftUSBHubPort 对象(ISoftUSBHubPort) ，这些对象表示集线器上的一组端口。可以使用 SoftUSBHubPort::HotPlug和SoftUSBHub::Unplug 方法将设备附加到集线器或从集线器移除设备。当创建SoftUSBHub对象时，可以设置 SoftUSBHub::NbrPorts 属性，以确定集线器上端口的数量。创建SoftUSBHub对象将自动用指定数量的SoftUSBHubPort对象填充SoftUSBHub::Ports 属性。

SoftUSBHub公开了包含集线器描述符的属性。SoftUSBHub::Status属性返回主机看到的当前集线器状态。SoftUSBHubPort::Status 属性返回主机看到的当前端口状态，并且 SoftUSBHubPort 还具有反映端口状态的各个位的单独属性，例如Enabled和Suspend。当测试应用程序使用完一个集线器时，它必须调用SoftUSBHub::Destroy 方法来清理在其操作期间分配的任何资源。

向微软发送有关此主题的评论

创建日期：2010/9/21

---

DSF HID协议转换器(SoftHIDProtocolXlator)

SoftHIDProtocolXlator对象(ISoftHIDProtocolXlator)用作模拟HID设备的HID-USB协议转换器。该对象根据USB HID设备类规范，代表USB HID设备模拟器配置并使用SoftUSBDevice对象(ISoftUSBDevice) 。下面的图描述了USB HID仿真体系结构。

                              HID设备的DSF仿真体系结构示意图

设备模拟器创建一个SoftHIDProtocolXlator 对象，并通过使用其HID描述符来设置其属性。HID设备模拟器向测试脚本和应用程序公开一个接口，这些脚本和应用程序能够启动HID事件，例如移动操纵杆或单击鼠标按钮。HID设备模拟器通过创建HID报告和调用SoftHIDProtocolXlator 对象上的方法以将它们传输到主机来实现这个接口。

SoftHIDProtocolXlator对象公开 ISoftHIDProtocolXlator双重接口，其具有以下属性和方法：

• DeviceType属性由设备模拟器设置，以确定正在模拟的HID设备的类型。该设备可以是键盘、鼠标或其他设备。
• DSFDevice属性返回SoftHIDProtocolXlator对象的SoftUSBDevice对象使用的DSFDevice对象（来自SoftUSBDevice::DSFDevice 属性）。
• HIDDescriptor.属性由设备模拟器设置为SoftUSBHIDDescriptor对象，以确定设备的HID描述符。
• 设备模拟器调用WriteReportDescriptor方法来确定设备的报表描述符的格式。报表描述符被指定为字节数组。
• 设备模拟器定期调用ReadOutputReport方法来接收从主机发送到设备的HID报告。HID报告作为字节数组返回。
• 设备模拟器调用WriteInputReport 方法向主机发送HID报告。HID报告被指定为字节数组。
• 设备模拟器调用WriteFeatureReport 方法向主机发送特征报告。特征报告被指定为字节数组。

SoftUSBHidDescriptor对象公开 ISoftUSBHidDescriptor双重接口，该接口具有与HID描述符的字段相对应的以下属性。（来自USB HID规范的描述符字段名在括号内）。

• HID属性(bcdHID)是标识HID类规范发布的数字表达式。
• CountryCode属性(bCountryCode) 是标识本地化硬件的国家代码的数字表达式。
• NumDescriptors属性(bNumDescriptors)是一个指定类描述符数量的数字表达式。（总是有至少一个，也就是报表描述符。）
• ClassDescriptorType属性(bDescriptorType) 是用于设置可选描述符类型的索引属性。
• DescriptorLength属性(wDescriptorLength)是一个索引属性，用于设置可选描述符的长度。

向微软发送有关此主题的评论

创建日期：2010/9/21