WDI IHV 驱动程序接口

WDI IHV 微型端口与任何其他 NDIS 微型端口驱动程序类似，它将遵循任何 NDIS 微型端口的开发做法和文档。 本机 WLAN 微型端口驱动程序对 NDIS 处理程序的责任在 MS 组件和 WDI IHV 驱动程序之间分配。 Microsoft WLAN 组件负责处理适用于所有Wi-Fi微型端口的 NDIS 要求，以便每个 IHV 不必重做所有工作。 在应用于 WDI IHV 微型端口时，本机 WLAN IHV 微型端口的 NDIS 处理程序的映射和行为更改如下所述。

• 驱动程序安装
• DriverEntry
• MiniportSetOptions
• MiniportInitializeEx
• MiniportHaltEx
• MiniportDriverUnload
• MiniportPause
• MiniportRestart
• MiniportResetEx
• MiniportDevicePnPEventNotify
• MiniportShutdownEx
• MiniportOidRequest
• MiniportCancelOidRequest
• NdisMIndicateStatusEx
• MiniportDirectOidRequest
• MiniportCancelDirectOidRequest
• MiniportSendNetBufferLists
• MiniportCancelSend
• MiniportReturnNetBufferLists
• WDI 处理程序：MiniportWdiOpenAdapter
• WDI 处理程序：MiniportWdiCloseAdapter

驱动程序安装

在系统上加载和安装 WDI IHV 微型端口驱动程序的方式没有变化。 INF 和安装过程类似于 IHV 本机 WLAN 微型端口驱动程序。 与现有的 NDIS 驱动程序一样，当需要加载 IHV 驱动程序才能使用 IHV 的 WLAN 适配器时，操作系统会调用 IHV 微型端口驱动程序的 DriverEntry 例程。

DriverEntry

操作系统直接调用 WDI IHV 微型端口驱动程序的 DriverEntry 例程。 IHV 微型端口遵循常规 NDIS 微型端口 DriverEntry 例程的大部分准则。 一个例外是，IHV 微型端口调用 NdisMRegisterWdiMiniportDriver 来告知操作系统启用 Microsoft WLAN 组件，而不是调用 NdisMRegisterMiniportDriver 。

以下是 NdisMRegisterWdiMiniportDriver 的关键参数。

• NDIS_MINIPORT_DRIVER_CHARACTERISTICS：这是本机Wi-Fi微型端口用于向 NDIS 注册的原始 NDIS 结构。 对于 WDI 模型，大多数处理程序参数都是可选的。 唯一必需的处理程序是 MINIPORT_OID_REQUEST_HANDLER 和 MINIPORT_DRIVER_UNLOAD。 MINIPORT_OID_REQUEST_HANDLER 用于将 WDI 消息传递到 IHV 驱动程序。 如果指定了任何其他处理程序，Microsoft WLAN 组件通常会在对处理程序执行自己的处理后调用处理程序。
• NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS：这是 WDI 微型端口驱动程序必须实现的新处理程序集。 IHV 驱动程序使用它为控制路径注册其他处理程序，并为数据路径注册完整的处理程序集。

当 IHV 微型端口调用 NdisMRegisterWdiMiniportDriver 时，Microsoft WLAN 组件更新 NDIS_MINIPORT_DRIVER_CHARACTERISTICS 的处理程序并调用 NDIS 的 NdisMRegisterMiniportDriver。 完成更新是为了 Microsoft WLAN 组件可以截获处理程序，它可以为 WDI IHV 微型端口驱动程序提供帮助/简化。

下面是 WDI IHV 微型端口驱动程序的 DriverEntry 过程的典型流程

有关 DriverEntry 的详细信息，请参阅 NDIS 微型端口驱动程序的 DriverEntry。

MiniportSetOptions

如上面的 DriverEntry 关系图中所示，如果 WDI IHV 微型端口已注册 MiniportSetOptions 处理程序，则操作系统会在调用 NdisMRegisterWdiMiniportDriver 的微型端口驱动程序的上下文中调用该函数。

如果 IHV 微型端口驱动程序使用 NdisSetOptionalHandlers 注册任何选项处理程序，则 Microsoft 组件可能无法通过 WDI 层对这些处理程序进行序列化。 因此，IHV 组件负责处理这些处理程序的任何同步要求。

MiniportInitializeEx

WDI 模型将 MiniportInitializeEx 行为拆分为多个 WDI 接口调用。

1. 调用 MiniportWdiAllocateAdapter。

   当操作系统找到 IHV 硬件的实例时，这是对 WDI IHV 微型端口驱动程序的第一次调用。 在此调用中，WDI 微型端口执行创建软件表示形式所需的操作， (设备的 MiniportAdapterContext) 。 它还确定有关要填充 NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES 结构的设备的信息。 当 Microsoft 组件向下发送 WDI 命令以执行特定初始化时，稍后将完成设备和Wi-Fi堆栈的实际初始化。

   使用从 WDI IHV 微型端口驱动程序获取的数据，Microsoft 组件调用 NdisMSetMiniportAttributes 并在 NDIS 上设置 NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES 。 NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES的大多数字段都由 Microsoft 组件使用默认值填充。 IHV 驱动程序必须填充 MiniportAdapterContext 和 InterfaceType 字段。

   从 IHV 微型端口驱动程序返回此调用后，它将通过其 MiniportOidRequest 处理程序开始接收 WDI 命令。 在此调用期间，Microsoft 组件可能无法执行重置/恢复操作，因此此处执行的任何活动都应快速且可靠。

2. 调用 MiniportWdiOpenAdapter。

   在 MiniportWdiAllocateAdapter 之后，Microsoft 组件调用 MiniportWdiOpenAdapter 以加载固件并初始化硬件。

3. 使用 MiniportOidRequest 的多个 WDI 命令。

   在 MiniportWdiOpenAdapter 之后，Microsoft 组件将以下任务/属性/调用发送到 IHV 微型端口。

   1. 调用 MiniportWdiTalTxRxInitialize 以初始化数据路径和交换处理程序。
   2. 调用 OID_WDI_GET_ADAPTER_CAPABILITIES 以获取适配器的功能。
   3. 调用 OID_WDI_SET_ADAPTER_CONFIGURATION 以配置适配器。
   4. 调用 OID_WDI_TASK_SET_RADIO_STATE 以设置初始无线电状态（如果它尚未处于预期状态）。
   5. 调用 MiniportWdiTalTxRxStart 以设置数据路径。
   6. 调用 OID_WDI_TASK_CREATE_PORT 以创建初始端口。

   其他命令也可能作为 Microsoft 组件的 MiniportInitializeEx 处理的一部分发送到 IHV 组件。 但是，在调用 MiniportWdiStartOperation 之前，Microsoft 组件不会发送任何需要无线通信的任务。 除了始终先发送 OID_WDI_TASK_OPEN 外，其他命令/调用的顺序可能会更改。

   使用从 WDI IHV 微型端口驱动程序获取的数据，Microsoft 组件调用 NdisMSetMiniportAttributes 并在 NDIS 上设置 NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES 和 NDIS_MINIPORT_ADAPTER_NATIVE_802_11_ATTRIBUTES 。

4. 调用 MiniportWdiStartOperation。

   这是 NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS 中的可选 WDI 微型端口处理程序，IHV 驱动程序可以使用该处理程序执行任何其他 MiniportInitializeEx 任务。 IHV 微型端口也可以使用它作为 Microsoft 组件已完成微型端口初始化的提示，并且微型端口可以启动任何所需的后台活动。

   下图显示了 MiniportInitializeEx 的流程。

   

   如果中间操作失败，Microsoft 组件将撤消以前的操作，使微型端口启动失败。 例如，如果 OID_WDI_TASK_CREATE_PORT 失败，则会清理数据路径，发送 OID_WDI_TASK_CLOSE ，微型端口将失败。

MiniportHaltEx

在本机Wi-Fi微型端口中， MiniportHaltEx 用于指示微型端口停止操作并清理适配器实例。 在 WDI 模型中，Microsoft 组件处理原始 MiniportHaltEx 调用，并将其拆分为多个 WDI 接口调用。

1. 调用 MiniportWdiStopOperation。

   这是 NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS 中的可选 WDI 微型端口处理程序，IHV 驱动程序可以使用该处理程序撤消它在 MiniportWdiStartOperation 中执行的操作。

2. 使用 MiniportOidRequest 的多个 WDI 命令。

   在 MiniportWdiStopOperation 之后，Microsoft 组件将任务/属性发送到 IHV 微型端口，以清理 IHV 驱动程序的当前状态。 此清理可能包括以下内容。

   1. 调用 OID_WDI_TASK_DISCONNECT/OID_WDI_TASK_STOP_AP 以断开所有现有连接。
   2. 调用 OID_WDI_TASK_DELETE_PORT 以删除所有创建的端口。
   3. 调用 MiniportWdiTalTxRxStop 以停止数据路径。
   4. 调用 MiniportWdiTalTxRxDeinitialize 以取消初始化数据路径。
   5. 调用 以清理硬件状态。 这会使用 IHV 驱动程序已注册的 MiniportWdiCloseAdapter 发送到 IHV。

3. 调用上述所有命令后，Microsoft 组件会调用 MiniportWdiFreeAdapter ，让 IHV 驱动程序删除它可能具有的任何软件状态。

下图显示了 MiniportHaltEx 的流程。

如果设备意外移除或系统关闭，则不执行 MiniportHaltEx 处理。 有关意外删除，请参阅 MiniportDevicePnPEventNotify 处理程序行为。 对于系统关闭，请参阅 MiniportShutdownEx 处理程序行为。

MiniportDriverUnload

MiniportDriverUnload 是在卸载 WDI IHV 微型端口之前调用的处理程序。 WDI IHV 微型端口驱动程序调用 Microsoft 组件来注销自身。 Microsoft 组件调用 NdisMDeregisterMiniportDriver。

下图显示了 MiniportDriverUnload 的流。

MiniportPause

NDIS MiniportPause 要求由 Microsoft 组件处理。 作为 MiniportPause 的一部分，Microsoft 组件停止数据路径并等待其清理。 WDI IHV 微型端口可以选择性地注册由 Microsoft 组件在完成数据路径清理后调用的 MiniportWdiPostAdapterPause 回调。

下图显示了 MiniportPause 的流程。

MiniportRestart

NDIS MiniportRestart 要求由 Microsoft 组件处理。 作为 MiniportRestart 的一部分，Microsoft 组件将撤消它作为 MiniportPause 的一部分执行的数据路径暂停工作。 WDI IHV 微型端口可以选择性地注册由 Microsoft 组件在完成重启数据路径后调用的 MiniportWdiPostAdapterRestart 回调。

下图显示了 MiniportRestart 的流程。

MiniportResetEx

MiniportResetEx 不由 Microsoft 组件处理。 WDI IHV 微型端口可以选择注册由 Microsoft 组件调用的 MiniportResetEx 回调。

MiniportDevicePnPEventNotify

MiniportDevicePnPEventNotify 用于通知 NDIS 驱动程序 PNP 事件，例如设备的意外删除。 当 NDIS 发送此通知时，它会首先转发到 WDI IHV 微型端口进行处理。 IHV 组件完成处理后，Microsoft 组件将对此事件执行相应的处理。 转发到 IHV 组件的调用不会与其他任务和回调一起序列化。

下图显示了 MiniportDevicePnPEventNotify 的流。

MiniportShutdownEx

MiniportShutdownEx 用于通知 NDIS 驱动程序有关系统关闭事件的信息。 当 NDIS 发送此通知时，它首先由 Microsoft 组件处理。 Microsoft 组件完成处理后，它将事件传递给 WDI IHV 微型端口进行处理。

下图显示了 MiniportShutdownEx 的流。

MiniportOidRequest

MiniportOidRequest 处理程序是 WDI IHV 微型端口必须实现的必需处理程序。 Microsoft 组件使用它将 WDI 命令提交到 IHV 微型端口。 它还用于将 Microsoft 组件不处理的 OID 转发到 IHV 微型端口。

对 WDI IHV 微型端口的 MiniportOidRequest 调用应被视为 WDI 命令的 M1 消息。 通过 NdisMOidRequestComplete 或通过 从 MiniportOidRequest) 返回非 PENDING 完成 OID (应被视为 WDI 任务/命令的 M3 消息。

对于每个 WDI 命令，有两个可能的字段可以为操作返回NDIS_STATUS代码 -- MiniportOidRequest 中的状态代码调用 (或 NdisMOidRequestComplete) ， WDI_MESSAGE_HEADER 字段中的状态代码 (OID 完成或通过 NdisMIndicateStatusEx) 。 Microsoft 组件在查看WDI_MESSAGE_HEADERStatus字段之前，始终从 OID 完成中查看 NDIS_STATUS 。 IHV 组件对 WDI OID 处理的期望如下所示。

1. WDI OID 使用 NDIS_OID_REQUESTRequestTypeNdisRequestMethod 提交到 IHV 组件，相应的消息和消息长度在 DATA 中。METHOD_INFORMATION。InformationBuffer 和 DATA。METHOD_INFORMATION。InputBufferLength 字段分别。
2. 如果处理命令时出现错误，IHV 组件会报告 OID 完成中的错误，如果 WDI_MESSAGE_HEADER 的“状态”字段Wi-Fi级别失败，则将其设置为不成功。
3. 对于任务和属性，请求的端口号位于 WDI_MESSAGE_HEADERPortId 字段中。 NDIS_OID_REQUEST中的 PortNumber 始终设置为 0。
4. 若要完成 OID， MiniportOidRequest 可以返回NDIS_STATUS_PENDING，并在以后使用 NdisMOidRequestComplete 以同步或异步方式 () 完成 OID。
5. 如果 IHV 组件使用NDIS_STATUS_SUCCESS完成 OID，则必须使用适当的字节数（包括WDI_MESSAGE_HEADER空间）填充 OID 请求的 BytesWritten 字段。
6. 如果 IHV 组件在 DATA 中没有足够的空间 。METHOD_INFORMATION。OutputBufferLength 字段用于填充响应，它将使用NDIS_STATUS_BUFFER_TOO_SHORT完成 OID 并填充 DATA。METHOD_INFORMATION。BytesNeeded 字段。 Microsoft 组件可能会尝试分配所请求大小的缓冲区，并将新请求提交到 IHV。
7. 如果是任务，则仅当任务报告为“已成功启动”时，才能指示任务的 M4 (NdisMIndicateStatusEx) - OID 完成成功且 OID 完成WDI_MESSAGE_HEADER中的状态为成功。

下图显示了映射到单个 WDI 命令的 NDIS OID 请求的示例。 当操作系统提交 OID 请求时，Microsoft 组件将其转换为 WDI OID 请求，并将 WDI OID 请求提交到 IHV 微型端口。 当 IHV 微型端口完成 OID 时，Microsoft 组件会相应地完成原始 OID 请求。

如果 OriginalOidRequest 映射到多个 WDI OidRequest，并且其中一个 WDI 请求失败，则 OriginalOidRequest 也会失败。 如果中间操作的子集已完成，Microsoft 组件将尝试撤消支持清理的操作。

下图显示了由 Microsoft 组件完成的 NDIS OID 请求的示例。 当操作系统提交 OID 请求时，Microsoft 组件将处理并完成 OID。 此 OID 不会传递到 WDI IHV 微型端口。

Microsoft 组件无法理解的 OID 将直接转发到 IHV 组件进行处理。

与本机Wi-Fi微型端口) 相比，WDI IHV 微型端口驱动程序 (MiniportOidRequest 的行为保持不变。 将序列化调用，IHV 微型端口可以通过调用 NdisMOidRequestComplete 以同步或异步方式完成调用。

MiniportCancelOidRequest

这是一个可选处理程序，由需要处理未映射到 WDI 消息的 OID 的 WDI IHV 微型端口使用。 此处理程序不用于任何 WDI OID。 WDI OID 必须快速完成，并且 IHV 微型端口驱动程序无需尝试取消挂起的 OID。 使用适当的取消任务 OID 请求处理 WDI 任务的取消。 对于未映射的 OID，预期行为由 NDIS 定义。

NdisMIndicateStatusEx

WDI IHV 微型端口使用 NdisMIndicateStatusEx 向 Microsoft 组件发送指示。 这些指示可能是未经请求的指示，例如 TKIP MIC 失败，或请求指示任务的完成 (M4) 。

下图显示了具有相应 NDIS/Native Wi-Fi指示的 WDI 指示示例。 当指示由 IHV 微型端口提交到 Microsoft 组件时，Microsoft 组件会将其转换为现有指示，并将其转发到操作系统。

下图显示了没有相应的 NDIS/Native Wi-Fi指示的 WDI 指示示例。 这由 Microsoft 组件处理。

下图显示了 Microsoft 组件无法识别的指示。 指示按原样转发到操作系统。

与本机Wi-Fi微型端口) 相比，WDI IHV 微型端口驱动程序 (NdisMIndicateStatusEx 的行为保持不变。

MiniportDirectOidRequest

这是一个可选处理程序，如果 WDI IHV 微型端口驱动程序需要处理未映射到 WDI 消息的直接 OID，则由该驱动程序注册。 Wi-Fi Direct 的所有现有 Direct OID 都映射到 WDI 消息，因此不需要此处理程序即可支持该功能。 Microsoft 组件不序列化不支持的 Direct OID。

MiniportCancelDirectOidRequest

这是一个可选处理程序，由需要处理未映射到 WDI 消息的直接 OID 的 WDI IHV 微型端口使用。 对于未映射的 OID，预期行为由 NDIS 定义。

MiniportSendNetBufferLists

此处理程序不在 WDI IHV 微型端口驱动程序中使用，不应提供。 Microsoft 组件使用通过 NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS 注册的数据路径处理程序将发送数据包提交到 IHV 微型端口。

MiniportCancelSend

此处理程序不用于 WDI IHV 微型端口驱动程序，不应提供。

MiniportReturnNetBufferLists

此处理程序不用于 WDI IHV 微型端口驱动程序，不应提供。 Microsoft 组件使用通过 NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS 注册的数据路径处理程序将收到的数据包返回到 IHV 微型端口。

WDI 处理程序：MiniportWdiOpenAdapter

Microsoft 组件使用 MiniportWdiOpenAdapter 处理程序在 IHV 驱动程序上启动 Open Task 操作。 此调用必须快速完成，如果打开操作已成功启动，IHV 必须在此调用中返回NDIS_STATUS_SUCCESS，并调用传递到 MiniportWdiAllocateAdapterNDIS_WDI_INIT_PARAMETERS 参数的 OpenAdapterComplete 处理程序。

WDI 处理程序：MiniportWdiCloseAdapter

Microsoft 组件使用 MiniportWdiCloseAdapter 处理程序在 IHV 驱动程序上启动关闭任务操作。 此调用必须快速完成，如果打开的操作已成功启动，IHV 必须在此调用中返回NDIS_STATUS_SUCCESS，并调用传递到 MiniportWdiAllocateAdapterNDIS_WDI_INIT_PARAMETERS 参数的 CloseAdapterComplete 处理程序。