共用方式為

將 NDIS 迷你埠驅動程式移植到 NetAdapterCx

  • 發行項

此頁面描述如何將 NDIS 6.x 迷你埠驅動程序轉換成 NetAdapterCx 用戶端驅動程式。

如需 WDF 的一般資訊，請檢閱 WDF 驅動程式開發指南。

編譯設定

在 Visual Studio 中開啟現有的 NDIS 迷你埠驅動程式專案，並使用下列步驟將它轉換成 KMDF 專案。

  1. 首先，流覽至 [設定屬性->驅動程式 設定 驅動程式>模型]，並確認驅動程式的類型已設定為 KMDF，且 KMDF 版本主要和 KMDF 版本次要都是空的。

  2. 在專案屬性中，開啟 Driver 設定-Network> Adapter Driver，並將 [鏈接到網络適配器類別延伸模組] 設定為 [是]。

    • 如果您轉換的驅動程式仍然會呼叫 NDIS API，請繼續連結至 ndis.lib。

  3. 移除 NDIS 預處理器宏，例如 NDIS650_MINIPORT=1。

  4. 將下列標頭新增至每個原始程序檔（或新增至您的通用/先行編譯標頭）：

    #include <ntddk.h>
#include <wdf.h>
#include <netadaptercx.h>

  5. 將標準 WDF 裝飾新增至您的 INF：

    [Yourdriver.Wdf]
KmdfService = Yourdriverservice, Yourdriver.wdfsect

[Yourdriver.wdfsect]
KmdfLibraryVersion = <insert here>

  6. 將新的必要的網路關鍵字新增至 INF 的 NT 區段：

    • *If 連線 orPresent

    • *連線 ionType

    • *DirectionType

    • *AccessType

    • *HardwareLoopback

      如需這些關鍵詞和範例的詳細資訊，請參閱 NetAdapterCx 用戶端驅動程式的 INF 檔案。

驅動程式初始化

從 DriverEntry 移除對 NdisMRegisterMiniportDriver 的呼叫，然後新增下列專案：

WDF_DRIVER_CONFIG_INIT(&config, EvtDriverDeviceAdd);
status = WdfDriverCreate(. . . );
if (!NT_SUCCESS(status)) {
  return status;
}

如果已設定，請從呼叫 WdfDriverCreate 移除 WdfDriverInitNoDispatchOverride 旗標。

DriverUnload 是 WDF 網路用戶端驅動程式的選擇性例程，因此您可以視需要將其移除。 請勿從 DriverUnload 呼叫 NdisMDeregisterMiniportDriver。

裝置初始化

接下來，您會將程式代碼從 MiniportInitializeEx 散發到適當的 WDF 事件回呼處理程式，其中幾個是選擇性的。 如需回呼順序的詳細資訊，請參閱 網路適配器 WDF 用戶端驅動程式的電源啟動順序。

當您啟動網路適配器，但在呼叫 NetAdapterStart 之前，您將會呼叫相當於 NdisMSetMiniportAttributes 的方法。 不過，客戶端驅動程式會呼叫不同的函式來設定不同類型的功能，而不是使用泛型 NDIS_MINIPORT_ADAPTER_ATTRIBUTES 結構呼叫一個例程。

如需您需要提供回呼的資訊，以及啟動網路適配器的時機，請參閱 裝置和適配卡初始化。

從登錄讀取設定

接下來，以方法取代對 NdisOpenConfigurationEx 和相關函式的 NetConfiguration* 呼叫。 這些 NetConfiguration* 方法與 Ndis*Configuration* 函式類似，您不需要重新建構程序代碼。

如需詳細資訊，請參閱 存取組態資訊。

從使用者模式接收 I/O 控制代碼 （IOCTLs）

如果您的 NDIS 驅動程式呼叫 NdisRegisterDeviceEx，則請閱讀本節，此例程是用來建立控制裝置物件 （CDO） 以從使用者模式接收 IOCTLs 的例程。

以下是在 WDF 網路用戶端驅動程式中執行這項操作的兩種方式。

最直接的埠是從用戶端的 EVT_WDF_DRIVER_DEVICE_ADD 回呼呼叫 WdfControlDeviceInitAllocate 來建立控制裝置物件。 如需詳細資訊，請參閱 使用控制裝置物件。

不過，建議的解決方案是建立裝置介面，如使用裝置介面中所述。

完成裝置初始化

此時， EVT_WDF_DRIVER_DEVICE_ADD，您可以執行任何您想要初始化裝置的任何動作，例如配置中斷。

處理電源狀態變更通知

WDF 用戶端驅動程式不會收到電源狀態變更OID_PNP_SET_POWER。

相反地，WDF 用戶端會註冊選擇性回呼函式來接收電源狀態變更通知。 如需概觀，請參閱 在函式驅動程式中支援 PnP 和電源管理。

一般而言，OID_PNP_SET_POWER處理程式中的程式代碼會移至EVT_WDF_DEVICE_D0_EXIT和EVT_WDF_DEVICE_D0_ENTRY。

由於WDF電源狀態機器稍有不同，您可能需要對程式代碼進行次要修改。

具體而言，在其 MiniportInitializeEx 回呼函式中，NDIS 迷你埠驅動程式會執行一次性初始化工作，以及讓裝置進入 D0 狀態的工作。 然後，它會重複工作，移至其 OID_PNP_SET_POWER 處理程式中的 D0。

相反地，WDF 用戶端會在EVT_WDF_DEVICE_D0_ENTRY之前，在事件回呼中執行一次性初始化工作，在此期間，裝置處於低功率狀態。 然後它會執行工作，以在 EVT_WDF_DEVICE_D0_ENTRY 中移至 D0。

總結來說，在 WDF 中，您會將「移至 D0」程式代碼放在一個位置，而不是兩個。

如需回呼順序的詳細資訊，請參閱 NetAdapterCx 用戶端驅動程式的 Power-Up 序列。

查詢和設定電源管理功能

同樣地，WDF 用戶端驅動程式不會收到 OID_PM_PARAMETERS 來查詢或設定網路適配器的電源管理硬體功能。

相反地，驅動程式會從 NETPOWERSETTINGS 對象查詢必要的網路喚醒 （WoL） 組態。 如需詳細資訊，請參閱 設定電源管理。

您返回的實際旗標具有與 NDIS 6 迷你埠相同的語意，因此您不需要對邏輯進行深層變更。 主要差異在於，您現在可以在關閉電源順序期間查詢這些旗標。 請參閱 NetAdapterCx 用戶端驅動程式的向下電源順序。

移動此程式代碼之後，您可以刪除OID_PNP_SET_POWER和OID_PM_PARAMETERS的 OID 處理程式。

因為 NetAdapter 架構會在主機使用網路介面時將您的裝置保持在 D0，用戶端通常不會實作電源邏輯;預設的 NetAdapter 電源行為已足夠。

資料路徑

數據路徑程序設計模型已大幅變更。 以下是一些主要差異：

  • 在 NetAdapter 模型中，網路流量不再是每個適配卡，就像在 NDIS 中一樣，而是每個 WDF 佇列。 請參閱 建立 I/O 佇列。
  • NetAdapterCx 不是NET_BUFFER_LIST和NET_BUFFER集區，而是引進由網路封包組成的通道緩衝區，其對應至 NDIS，如下所示：
    • NET_PACKET類似於NET_BUFFER_LIST + NET_BUFFER。
    • NET_PACKET_FRAGMENT類似於記憶體描述元清單 （MDL）。 每個 NET_PACKET 都有一或多個。
    • 如需取代結構及其使用方式的詳細資訊，請參閱 封包描述元和延伸模組。
  • 在NDIS 6.x中，迷你埠必須處理開始和暫停語意。 在 NetAdapterCx 模型中，情況不再是這樣。
  • EVT_RXQUEUE_ADVANCE回呼類似於NDIS 6.x中的MINIPORT_RETURN_NET_BUFFER_LISTS。
  • EVT_TXQUEUE_ADVANCE回呼類似於 NDIS 6.x 中的MINIPORT_SEND_NET_BUFFER_LISTS。

裝置移除

WDF NIC 驅動程式的裝置移除與任何其他 WDF 設備驅動器相同，不需要網路特定的處理。 網路數據路徑會先關閉，後面接著 WDF 裝置。 如需 WDF 關機的相關信息，請參閱 使用者拔除裝置。

您的 MiniportHaltEx 處理程式可能會分散在EVT_WDF_DEVICE_D0_EXIT和EVT_WDF_DEVICE_RELEASE_HARDWARE之間。

WDF 用戶端不需要刪除 NetAdapter 或其建立的任何數據路徑佇列。 WDF 會自動刪除這些物件。

您可以刪除 MiniportShutdownEx、MiniportResetEx 和 MiniportCheckForHangEx。 不再支持這些回呼。

NDIS-WDF 函式對等專案

大部分 NdisXxx 的函式都可以取代為 WDF 對等專案。 一般而言，您應該發現您只需要從 NDIS.SYS匯入的很少功能。

如需函式對等項目的清單，請參閱 NDIS-WDF 函式對等專案。

偵錯

請參閱 偵錯 NetAdapterCx 用戶端驅動程式。

！ndiskd.netadapter 調試程式延伸模組會顯示類似 ！ndiskd.miniport 針對 NDIS 6 驅動程序顯示的結果。

結論

使用本主題中的步驟，您應該會有啟動和停止裝置的工作驅動程式。

注意：NetAdapterCx 目前不支援 iSCSI 開機。