共用方式為

使用 NetAdapterCx PLDR 復原沒有回應的 NIC

  • 發行項

NetAdapterCx 透過平台層級裝置重設 (PLDR) ，提供重設和復原故障網路裝置的有效方式。 若未重新開機整個 Windows 系統，PLDR 作業會卸載受影響的網路裝置堆疊，以確保其硬體和驅動程式會從空白狀態重新開機。 NetAdapterCx 也可讓用戶端驅動程式從失敗的裝置收集診斷，再進行平台層級重設。

偵測到異常裝置行為時，就會觸發 PLDR。 它可以由下列其中一項觸發：

  • 作業系統 (作業系統) 。 例如，當傳輸中封包卡在驅動程式太長時，OS 端可能會觸發 PLDR。

  • 獨立硬體廠商 (IHV) 用戶端驅動程式。 例如，當驅動程式偵測到其裝置沒有回應其控制命令時，用戶端驅動程式可能會要求 NetAdapterCx 觸發 PLDR。

若要提供方便使用的裝置失敗和復原，我們建議 IHV 和原始設備製造商 (OEM) 支援其網路裝置的 PLDR。 如需 PLDR 的詳細資訊，請參閱 重設和復原裝置。 NetAdapterCx 不會透過功能層級裝置重設來復原網路裝置。

註冊選擇性診斷集合回呼

在 NetAdapterCx 重設和復原程式中，用戶端驅動程式可以在裝置為平台層級重設之前，從失敗的裝置收集裝置特定的診斷。 IHV 和 Microsoft 可以在失敗後分析中使用此資料來改善其產品的品質。

註冊NET_DEVICE_RESET_CAPABILITIES

用戶端驅動程式必須在其EVT_WDF_DRIVER_DEVICE_ADD回呼函式中初始化和註冊NET_DEVICE_RESET_CAPABILITIES結構，才能收集裝置特定的診斷。

NET_DEVICE_RESET_CAPABILITIES 包含：

  • 唯一的 GUID。 IHV 會指定此 GUID，並在稍後用來識別和擷取記憶體傾印中的重設診斷。 例如， .enumtag 命令可用來擷取診斷。

  • EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS事件回呼函式。 NetAdapterCx 會叫用此回呼來收集診斷。 如果用戶端驅動程式提供 EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS回 呼，NetAdapterCx 會使用 專用 執行緒在用戶端驅動程式上叫用它。

下列範例示範如何向 NetAdapterCx 註冊 NET_DEVICE_RESET_CAPABILITIES ：

EVT_WDF_DRIVER_DEVICE_ADD EvtWdfDriverDeviceAdd;
EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS EvtDeviceCollectResetDiagnostics;

NTSTATUS EvtWdfDriverDeviceAdd(
    WDFDRIVER Driver,
    PWDFDEVICE_INIT DeviceInit
)
{
    ...

    NET_DEVICE_RESET_CAPABILITIES resetCapabilities;
    NET_DEVICE_RESET_CAPABILITIES_INIT(
        &resetCapabilities,
        DUMMY_GUID,
        EvtDeviceCollectResetDiagnostics);
    NetDeviceInitSetResetCapabilities(DeviceInit, &resetCapabilities);

    ...
}

如需如何初始化 NET_DEVICE_RESET_CAPABILITIES 結構的資訊，請參閱 NET_DEVICE_RESET_CAPABILITIES_INIT。

若要瞭解如何將 NET_DEVICE_RESET_CAPABILITIES 結構公告至 NetAdapterCx，請參閱 NetDeviceInitSetResetCapabilities。

實 作EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS

重設和復原順序可以隨時發生。 因此，用戶端驅動程式 的EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS 回呼實作必須考慮下列事項：

  • NetAdapterCx 會將 EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS 回呼與電源 關閉順序期間可能發生的其他回呼同步處理。 用戶端驅動程式可以假設 NetAdapterCx 不會叫用回呼，例如封包佇列取消/停止、硬體釋放和裝置物件刪除，直到 EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS 傳回為止。

  • 用戶端驅動程式在處理診斷收集時必須特別小心，以避免死結。 它必須考慮硬體可能已處於失敗狀態。

  • 請務必儘快完成 EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS ，讓 PLDR 程式的其餘部分可以繼續進行。 EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS 必須可靠，而且必須在 3 秒內傳回。

  • NetAdapterCx 一律會在 PASSIVE_LEVEL 叫用EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS。

若要將診斷提交至 NetAdapterCx，用戶端驅動程式會執行下列步驟：

  1. 從分頁或非分頁集區預先配置一般緩衝區，以收集重設診斷。 驅動程式應該預先配置此緩衝區，以避免在裝置重設期間發生記憶體不足錯誤。

  2. 在 EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS回 呼內，藉由呼叫 NetDeviceStoreResetDiagnostics API，將診斷提交為一般資料緩衝區。 用戶端驅動程式必須在 PASSIVE_LEVEL呼叫 NetDeviceStoreResetDiagnostics API。

  3. 一旦 NetDeviceStoreResetDiagnostics 傳回，請釋放資料緩衝區。

重要

NetDeviceStoreResetDiagnostics API 只能在EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS回呼中呼叫。 在先前 的 NetDeviceStoreResetDiagnostics 傳回之後，它也無法用來重新提交診斷資料。 違反上述任一情況會導致錯誤檢查。

重要

重設診斷的大小限制為 1 MB。

用戶端驅動程式如何要求 PLDR

用戶端驅動程式會在偵測到裝置失敗時，使用 NetAdapterCx NetDeviceRequestReset API 觸發 PLDR。 NetDeviceRequestReset 會立即傳回用戶端驅動程式。 NetAdapterCx 重設和復原順序中所述的重設和復原順序會觸發，而且對NetDeviceRequestReset呼叫是非同步。

在任何指定時間只能執行一個 PLDR 作業。 因此，當 PLDR 作業已啟動時， NetDeviceRequestReset 的後續呼叫沒有任何作用。

如果已起始關閉電源序列，則呼叫NetDeviceRequestReset也沒有任何作用。

NetAdapterCx 重設和復原順序

當 OS 或用戶端驅動程式觸發 PLDR 時，會發生下列順序：

  1. 收集重設診斷：NetAdapterCx 會叫用用戶端驅動程式 的EVT_NET_DEVICE_COLLECT_RESET_DIAGNOSTICS回 呼，以從失敗的裝置收集診斷。 例如，驅動程式可能會收集裝置韌體快照集。 此步驟是選擇性的，只有在用戶端驅動程式已註冊 NET_DEVICE_RESET_CAPABILITIES 結構時才會發生。 否則，NetAdapterCx 將會略過此步驟。

  2. 執行 PLDR：NetAdapterCx 會執行平台層級裝置重設作業。 NetAdapterCx 電源會回收硬體，並卸載軟體裝置堆疊。

下圖說明 NetAdapterCx 重設和復原順序：

說明 NetAdapterCx 重設和復原順序的流程圖。