MINIPORT_CHECK_FOR_HANG回呼函式 (ndis.h)

發行項
02/29/2024

警告

不建議所有 NDIS 6.83 和更新版本的驅動程式使用 MiniportCheckForHangEx 和 MiniportResetEx 回呼函式。如需詳細資訊，請參閱 NDIS 6.83 和更新版本中的 Check-for-Hang 和 Reset 作業。

NDIS 會呼叫迷你埠驅動程式的 MiniportCheckForHangEx 函式，以檢查迷你埠適配卡的作業狀態，此適配卡代表 NIC (NIC) 。

注意迷你埠驅動程式可以使用 MINIPORT_CHECK_FOR_HANG 類型來宣告此函式。

注意從 NDIS 6.30 開始，此函式不得註冊在低電源 SoC 平臺上執行的驅動程式，以避免定期檢查-for-Hang 活動所造成的負面影響。

語法

MINIPORT_CHECK_FOR_HANG MiniportCheckForHang;

BOOLEAN MiniportCheckForHang(
  [in] NDIS_HANDLE MiniportAdapterContext
)
{...}

參數

[in] MiniportAdapterContext

迷你埠驅動程式在其 MiniportInitializeEx 函式中配置的內容區域句柄。迷你埠驅動程式會使用此內容區域來維護迷你埠配接器的狀態資訊。

傳回值

如果驅動程序判斷 NIC 未運作，而 NDIS 應該呼叫驅動程式的 MiniportResetEx 函式，MiniportCheckForHangEx 會傳回 TRUE。如需詳細資訊，請參閱＜備註＞一節。

備註

迷你埠驅動程式會在呼叫時指定 MiniportCheckForHangEx 進入點 NdisMRegisterMiniportDriver 函式。

中繼驅動程式不需要 MiniportCheckForHangEx。

MiniportCheckForHangEx 不只檢查 NIC 的內部狀態，並在偵測到 NIC 未正確運作時傳回 TRUE 。

根據預設，NDIS 會每隔兩秒呼叫 MiniportCheckForHangEx 。基於這個理由，迷你埠驅動程式的 MiniportCheckForHangEx 函式應該儘快傳回。

注意從 NDIS 6.30 開始，使用高容錯的聯合定時器來測量 MiniportCheckForHangEx 呼叫之間的間隔。因此，此例程不應用於任何時間敏感性作業。

如果 MiniportCheckForHangEx 傳回 TRUE，NDIS 會呼叫迷你埠驅動程式的 MiniportResetEx 函式。

如果迷你埠驅動程式未在連續兩次呼叫 MiniportCheckForHangEx 內完成 OID 要求，NDIS 可以呼叫驅動程式的 MiniportResetEx 函式。不過，若要避免不必要的重設，驅動程式的 MiniportInitializeEx 函式可以在呼叫時設定適當的 CheckForHangTimeInSeconds 值來擴充 check-for-hang 逾時間隔 NdisMSetMiniportAttributes 函式。

如需設定 CheckForHangTimeInSeconds 逾時值的詳細資訊，請參閱 Miniport Adapter Check-for-Hang 和 Reset Operations。

注意從 NDIS 6.30 開始，如果 Miniport 驅動程式偵測到 NIC 尚未在逾時期間過期之前完成暫止傳送要求， MiniportCheckForHangEx 就必須傳回 TRUE 。逾時期間是驅動程式特定的，但我們建議使用 2 秒的逾時期間。

MiniportCheckForHangEx 可以先占中斷。

NDIS 會在 IRQL = PASSIVE_LEVEL呼叫 MiniportCheckForHangEx 。

例子

若要定義 MiniportCheckForHangEx 函式，您必須先提供函式宣告，以識別您要定義的函式類型。 Windows 提供一組驅動程式的函式類型。使用函式類型宣告函式有助於驅動程式的程式代碼分析、靜態驅動程序驗證器 (SDV) ，以及其他驗證工具會尋找錯誤，而且這是撰寫 Windows 操作系統驅動程式的需求。

例如，若要定義名為「 MyCheckForHangEx」的 MiniportCheckForHangEx 函式，請使用 MINIPORT_CHECK_FOR_HANG 類型，如下列程式代碼範例所示：

MINIPORT_CHECK_FOR_HANG MyCheckForHangEx;

然後，實作您的函式，如下所示：

_Use_decl_annotations_
BOOLEAN
 MyCheckForHangEx(
    NDIS_HANDLE  MiniportAdapterContext
    )
  {...}

MINIPORT_CHECK_FOR_HANG函式類型定義於 Ndis.h 頭檔中。若要在執行程式代碼分析工具時更精確地識別錯誤，請務必將 Use_decl_annotations 註釋新增至函式定義。 Use_decl_annotations批注可確保使用頭檔中套用至MINIPORT_CHECK_FOR_HANG函式類型的批注。如需函式宣告需求的詳細資訊，請參閱使用 NDIS 驅動程式的函式角色類型來宣告函式。

如需 Use_decl_annotations的詳細資訊，請參閱標註函式行為。