使用 DSS 进行 MB 调制解调器日志记录
注意
如果计划为调制解调器提供支持 MBIM_CID_MODEM_LOGGING_CONFIG，请在此页上提供反馈，以便我们提供最佳支持。 此 CID 目前是实验性的，尚未使用调制解调器进行测试，因为没有支持它。
本主题介绍通过 Microsoft 扩展到 USB MBIM 1.0 规范的新标准 Windows 移动宽带（MBB）日志记录接口，该规范在 Windows 10 版本 1903 及更高版本中提供。
使用此新的日志记录接口，OS 可以通过 MBIM CID 命令通知 MBB 设备启动、停止和刷新 OS 文件系统的日志。 鉴于调制解调器日志记录有效负载的非 IP 性质，MBB 服务用来将日志记录有效负载传输到 OS 的数据通道使用 MBB 数据服务流（DSS）。 DSS 在移动宽带接口模型 （MBIM） 1.0 规范中定义。
OS 使用一组特定于 Windows 的 MBB 日志记录配置抽象了调制解调器在整个 MBB 生态系统中的诊断功能和配置。 这些 MBB 日志记录配置使调制解调器的供应商能够将 OS MBB 日志记录要求映射到适当的内部日志记录配置。 OS 抽象和定义的日志记录配置包括 MBB 日志记录详细级别和最大刷新时间。
调制解调器将不断填充其日志记录缓冲区（最大缓冲区大小），直到填充段，MBIM 框架将段传输到 OS，或者在达到最大刷新时间时刷新其缓冲区的内容（即使未填充段）。 OS 定义了一组标准 Windows MBB 日志记录配置级别，本主题稍后将对此进行介绍。 每个配置级别指定 MBB 日志记录详细信息和详细程度的 OS 抽象。
MBB 配置级别的 OS 抽象映射到调制解调器的适当内部调制解调器配置。 OS 不会向 OS MBB 配置级别以外的调制解调器提供任何其他配置有效负载，例如日志记录筛选器或掩码。
对于支持 MBB 日志记录的调制解调器，除 MBIMLoggingLevelOem 之外的所有 MBB 日志记录配置级别必须存在于所有 BSP 变体中。 换句话说，IHV 或 OEM 必须在 BSP 的生产版本和 R&D 版本中都支持 MBB 日志记录的 PROD 或 LAB 级别。 MBB 日志记录的实验室级别只能从 OS 中禁用。
这种新的日志记录接口的设计使用控制通道来设置日志记录参数，并使用数据通道接收调制解调器日志，因为数据通道旨在传输批量调制解调器数据。 此设计的优点是，无需通过控制通道传输大容量数据，从而保持设备性能一致。 它还可很好地缩放以提高吞吐量。 数据通道由 DSS 命令操作。 调制解调器的示例流可能如下所示：
- OS 将 MBIM_CID_MODEM_LOGGING_CONFIG CID 发送到调制解调器，以配置日志记录参数，例如 MaxSegmentSize、MaxFlushTime 和 LoggingLevel。
- OS 收到来自调制解调器的成功响应后，它将MBIM_CID_DSS_CONNECT DSS 命令发送到具有用于调制解调器日志记录的特定 GUID 的调制解调器、MBIMDssLinkActivate 状态和唯一的 DSS 会话 ID。
- 收到成功状态代码后，OS 会准备从调制解调器接收片段。 这些片段称为 DataServiceSessionRead 数据包。
- DataServiceSessionRead 数据包将继续到达，直到 OS 发出另一个具有相同 DSS 会话 ID 和 MBIMDSSLinkDeactivate 状态的 MBIM_CID_DSS_CONNECT 命令。
调制解调器将任何日志写入新创建的数据通道后，调制解调器将调用 MbbDeviceReceiveDeviceServiceSessionData，该数据通过 WinRT 层：MobileBroadbandDeviceService 从中提供给应用。 调制解调器日志的格式应设置为可打印的字符串数据，可以重定向到 ETW 会话。
调制解调器日志记录数据路径
调制解调器日志记录使用 MBIM 数据服务流（DSS）传输用于记录有效负载的数据。 有关 DSS 的详细信息，请参阅 MBIM 1.0 规范的第 10.5.38 节。
连接或断开与 DSS 的连接或断开连接时，以下 GUID 用于调制解调器日志记录：
| GUID | 值 |
|---|---|
| ModemFileTransfer GUID | 0EBB1CEB-AF2D-484D-8DF3-53BC51FD162C |
以下流程图演示了 DSS 设置和拆解过程。
NDIS 接口扩展
Windows 10 版本 1903 中定义了以下 OID 以支持调制解调器日志记录。
MBIM 服务和 CID 值
| 服务名称 | UUID | UUID 值 |
|---|---|---|
| Microsoft 基本 IP 连接ivity 扩展 | UUID_BASIC_CONNECT_EXTENSIONS | 3d01dcc5-fef5-4d05-9d3a-bef7058e9aaf |
下表指定每个 CID 的 UUID 和命令代码，以及 CID 是否支持 Set、Query 或 Event （notification） 请求。 有关其参数、数据结构和通知的详细信息，请参阅本主题中的每个 CID 的各个部分。
| CID | UUID | 命令代码 | 设置 | 查询 | Notify |
|---|---|---|---|---|---|
| MBIM_CID_MODEM_LOGGING_CONFIG | UUID_BASIC_CONNECT_EXTENSIONS | 待定 | Y | Y | Y |
MBIM_CID_MODEM_LOGGING_CONFIG
此 CID 用于配置调制解调器收集的日志，以及它们通过 DSS 从调制解调器发送到主机的频率。 在启动日志记录会话之前，必须配置日志记录。 由于此 CID 是连接扩展的一部分，因此 IHV 支持此 CID 是可选的。 如果 IHV 支持通过 DSS 数据通道进行调制解调器日志记录，则必须将其指定为一项功能。 可以使用 MBIM_BASIC_CID_DEVICE_标准版RVICES CID 播发该功能。
参数
| 操作 | 设置 | 查询 | 通知 |
|---|---|---|---|
| 命令 | MBIM_MODEM_LOGGING_CONFIG | 不适用 | 不适用 |
| 响应 | MBIM_MODEM_LOGGING_CONFIG | MBIM_MODEM_LOGGING_CONFIG | MBIM_MODEM_LOGGING_CONFIG |
查询
查询当前的调制解调器日志记录配置。 不使用 MBIM_COMMAND_MSG的 InformationBuffer。 以下MBIM_MODEM_LOGGING_CONFIG结构用于MBIM_COMMAND_DONE的 InformationBuffer。
MBIM_MODEM_LOGGING_CONFIG
| Offset | 大小 | 字段 | 类型 | 描述 |
|---|---|---|---|---|
| 0 | 4 | 版本 | UINT32 | 此结构的版本号。 对于此结构的版本 1，此字段必须设置为 1 。 |
| 4 | 4 | MaxSegmentSize | UINT32 | 指定调制解调器发送的每个片段的段大小（以 KB 为单位）。 如果设备服务命令的调制解调器支持的最大片段大小超过设置的值，则此值将设置为支持的最大段大小。 |
| 8 | 4 | MaxFlushTime | UINT32 | 时间（以毫秒为单位），指示调制解调器在发送日志片段之前等待的最长时间。 如果收集的日志在自上次发送的日志片段以来在 MaxFlushTime 持续时间内未达到 MaxSegmentSize，则无论日志片段的大小如何，都会发送日志片段。 如果没有日志记录数据，则不会发送通知。 如果设备无法处理较小的刷新时间，则设备将返回它可以在响应中处理的时间。 对查询或集的响应包含当前配置的 MaxFlushTime。 |
| 12 | 4 | LevelConfig | MBIM_LOGGING_LEVEL_CONFIG | 配置收集日志的级别。 对查询或集的响应包含当前配置的 LevelConfig。 |
注意
如果调制解调器无法在请求 的 MaxSegmentSize 和 MaxFlushTimer 上向 OS 提供日志数据，则可以为这些参数选择自己的值，并将 OS 更新为设置响应或未经请求的事件。 如果 MaxSegmentSize 或 MaxFlushTimer 发生更改，OS 行为不会更改，因为它接收数据包而不考虑并将其转储到文件。
上述MBIM_MODEM_LOGGING_CONFIG结构中使用了以下MBIM_LOGGING_LEVEL_CONFIG枚举。
| 类型 | 值 | 说明 |
|---|---|---|
| MBIMLoggingLevelProd | 0 | 适用于来自零售或生产群体的遥测收集。 生成的日志应采用胶囊大小，并且仅包含关键调制解调器或 MBB 状态或故障信息。 |
| MBIMLoggingLevelLabVerbose | 1 | 旨在开发成熟度较低的 MBB 产品。 调制解调器的详细全堆栈捕获。 生成的调制解调器捕获应使 IHV 能够在日志期间重播并完全恢复捕获。 |
| MBIMLoggingLevelLabMedium | 2 | 适用于具有相对成熟度和稳定性的 MBB 产品的验证和现场测试。 详细程度和详细程度为 IHV 工程师提供了足够的数据点来对大多数 MBB 故障进行会审。 |
| MBIMLoggingLevelLabLow | 3 | 适用于自主机级日志记录。 完整堆栈捕获调制解调器的摘要级捕获。 启用对调制解调器状态和 OS 交互的突出显示级别了解。 |
| MBIMLoggingLevelOem | 4 | 保留供 OEM 和 IHV 内部使用。 |
设置
设置命令用于配置调制解调器日志记录的级别、段大小和最大刷新时间。 InformationBuffer 中使用MBIM_MODEM_LOGGING_CONFIG结构。
响应
MBIM_COMMAND_DONE中的 InformationBuffer 包含MBIM_MODEM_LOGGING_CONFIG结构。
未经请求的事件
对于调制解调器需要通知 OS 内部更改的情况，支持未经请求的事件。 目前，在 Windows 10 版本 1903 中，这些方案不会发生。
状态代码
此 CID 仅使用 MBIM 规范修订版 1.0 的第 9.4.5 节中定义的通用状态代码。
非活动期间 DSS 会话行为
下表介绍了 DSS 会话在非活动的各个阶段的行为方式：
| 场景 | DSS 会话状态 |
|---|---|
| 系统睡眠、仅调制解调器睡眠、重置和恢复 | DSS 会话保持打开状态 |
| 系统关闭、重启、休眠 | DSS 会话已关闭 |