MINIPORT_INITIALIZE回呼函式 (ndis.h)

發行項
03/08/2023

NDIS 會呼叫迷你埠驅動程式的 MiniportInitializeEx 函式，以初始化網路 I/O 作業的迷你埠適配卡。

注意您必須使用 MINIPORT_INITIALIZE 類型來宣告函式。如需詳細資訊，請參閱下列範例一節。

語法

MINIPORT_INITIALIZE MiniportInitialize;

NDIS_STATUS MiniportInitialize(
  [in] NDIS_HANDLE NdisMiniportHandle,
  [in] NDIS_HANDLE MiniportDriverContext,
  [in] PNDIS_MINIPORT_INIT_PARAMETERS MiniportInitParameters
)
{...}

參數

[in] NdisMiniportHandle

NDIS 提供的句柄，可識別迷你埠驅動程序應該初始化的迷你埠適配卡。

[in] MiniportDriverContext

驅動程式所配置內容區域的句柄，其中驅動程式會維護狀態和設定資訊。迷你埠驅動程式已將此內容區域傳遞至 NdisMRegisterMiniportDriver 函式。

[in] MiniportInitParameters

的指標 NDIS_MINIPORT_INIT_PARAMETERS 結構，定義迷你埠配接器的初始化參數。

傳回值

MiniportInitializeEx 可以傳回下列其中一個狀態值：

傳回碼	Description
NDIS_STATUS_SUCCESS	MiniportInitializeEx 已設定並設定迷你埠配接器，並配置驅動程式必須執行網路 I/O 作業的所有資源。
NDIS_STATUS_NOT_ACCEPTED	MiniportInitializeEx 無法取得迷你埠配接器，以接受 MiniportInitializeEx 從登錄取得的組態參數。
NDIS_STATUS_RESOURCES	MiniportInitializeEx 無法配置資源來執行網路 I/O 作業。 MiniportInitializeEx 應該呼叫 NdisWriteErrorLogEntry 函式，以識別資源衝突 (例如 I/O 連接埠範圍、中斷向量、裝置記憶體範圍，視需要) 。提供錯誤記錄檔記錄會提供使用者或系統管理員資訊，可用來重新設定計算機，以避免這類硬體資源衝突。
NDIS_STATUS_FAILURE	MiniportInitializeEx 因為上述清單中的 MiniportInitializeEx 以外的原因而失敗。驅動程式應該使用指定失敗原因的參數來呼叫 NdisWriteErrorLogEntry 。

備註

NDIS 會將 MiniportInitializeEx 呼叫為系統 PnP 作業的一部分。驅動程式呼叫來指定 MiniportInitializeEx 進入點 NdisMRegisterMiniportDriver 函式來自 DriverEntry 例程。 NDIS 可以在 DriverEntry 傳回之後呼叫 MiniportInitializeEx。如需詳細資訊，請參閱 NDIS Miniport Drivers 的 DriverEntry。

針對 NDIS 中繼驅動程式，NDIS 可以在的內容中呼叫 MiniportInitializeEx NdisIMInitializeDeviceInstanceEx 函式或傳回之後。這類驅動程式的 ProtocolBindAdapterEx 函式通常會呼叫 NdisIMInitializeDeviceInstanceEx。

驅動程式可以註冊為合併的迷你埠驅動程式和中繼驅動程式， (請參閱 NdisMRegisterMiniportDriver) 。這類迷你埠中繼驅動程序的運作方式類似於分層在實體迷你埠驅動程式上的中繼驅動程式。對於 miniport-intermediate 驅動程式的每個虛擬或實體裝置實例，如果 IMMiniport 登錄機碼設定為 DWORD：0x0000001，NDIS 會呼叫驅動程式為虛擬設備註冊的 MiniportInitializeEx 函 式。否則，NDIS 會呼叫驅動程式為實體裝置註冊的驅動程式 MiniportInitializeEx 函 式。

在 MiniportInitializeEx 傳回之前，NDIS 不會針對要初始化的迷你埠配接器提交任何要求。迷你埠配接器處於 初始化 狀態。

若要取得迷你埠配接器的組態信息，驅動程式會呼叫 NdisOpenConfigurationEx 和 NdisReadConfiguration 函式。驅動程式可以呼叫 NdisMGetBusData 函式來取得總線特定資訊。

迷你埠驅動程序必須呼叫 NdisMSetMiniportAttributes 函式並提供 NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES 結構，其中包含下列屬性：

驅動程式配置內容區域的句柄。
適當的屬性旗標。
呼叫它的超時時間間隔 MiniportCheckForHangEx 函式。
介面型別。

迷你埠驅動程式會在 NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES 的 MiniportAdapterContext 成員上傳遞 NdisMSetMiniportAttributes 句柄。驅動程式會在此內容區域中維護指定迷你埠配接器的狀態資訊。 NDIS 會將此句柄當做輸入參數傳遞至其他 MiniportXxx 函式。

迷你埠驅動程序必須在中設定屬性在NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES 結構中設定註冊屬性之後，以及在設定任何其他屬性之前，NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES結構。

MiniportInitializeEx 也可以配置資源，例如：

非分頁集區內存
NET_BUFFER 和 NET_BUFFER_LIST 結構集區
微調鎖定
計時器
IO 埠
DMA
共用記憶體
中斷

如果驅動程式指出使用接收 NdisMIndicateReceiveNetBufferLists 函式， MiniportInitializeEx 函式應該呼叫 NdisAllocateNetBufferListPool 和 NdisAllocateNetBufferPool 函式，並儲存這些 NDIS 函式所傳回的句柄。一般而言，驅動程式後續使用 NdisMIndicateReceiveNetBufferLists 指出的網路數據會參考已使用配置的結構 NdisAllocateNetBufferAndNetBufferList 函式。驅動程式也可以使用與 NdisAllocateNetBuffer 一起配置的結構，以及 NdisAllocateNetBufferList 函式。

如果驅動程式函式，除了 MiniportInterrupt 函式之外，共用資源、 MiniportInitializeEx 應該呼叫 NdisAllocateSpinLock 函式，以設定同步處理這類共用資源存取所需的任何微調鎖定。其他驅動程式函式與 MiniportInterrupt 共用的資源，例如 NIC 快取器，會受到驅動程式設定的中斷物件所保護 NdisMRegisterInterruptEx 函式。驅動程式函式會呼叫來存取這些資源 NdisMSynchronizeWithInterruptEx 函式。

MiniportInitializeEx 可以使用驅動程式提供的 NetTimerCallback 函式和定時器對象的驅動程式配置記憶體指標來呼叫 NdisAllocateTimerObject 函式。驅動程式可以設定多個 NetTimerCallback 函式，每個函式都有自己的定時器物件。驅動程式可以呼叫 NdisSetTimerObject 函式來啟用定期 NetTimerCallback 函式。驅動程式也可以呼叫 NdisSetTimerObject 函式，以啟用一次性 NetTimerCallback 函式。

MiniportInitializeEx 必須呼叫 NdisMSetMiniportAttributes 函式在呼叫任何 NdisMXxx 函式之前，例如 NdisMRegisterIoPortRange 或 NdisMMapIoSpace 函式，會宣告迷你埠配接器的硬體資源。 MiniportInitializeEx 必須先呼叫 NdisMSetMiniportAttributes ，才能嘗試配置 DMA 作業的資源。

如果裝置支持總線主機 DMA，MiniportInitializeEx 必須呼叫 NdisMRegisterScatterGatherDma 函式在呼叫 NdisMSetMiniportAttributes 和呼叫之前 NdisMAllocateSharedMemory 函式。如果裝置支援從屬 DMA，MiniportInitializeEx 必須先呼叫 NdisMSetMiniportAttributes ，才能呼叫 NdisMRegisterDmaChannel 函式。

在 MiniportInitializeEx 呼叫之後 NdisMRegisterInterruptEx 函式，NDIS 可以呼叫驅動程式的 MiniportInterrupt 函式。如果 NIC 產生中斷，或 NIC 共用中斷的任何其他裝置產生中斷，則 NDIS 會呼叫 MiniportInterrupt 。請注意，迷你埠驅動程式會在呼叫 NdisMRegisterInterruptEx 時立即收到中斷，並持續收到中斷，直到其呼叫為止 NdisMDeregisterInterruptEx 函式會傳回。

MiniportInitializeEx 應該測試 NIC，以確定硬體已正確設定。如果驅動程式必須等候硬體發生狀態變更， MiniportInitializeEx 可以使用 NdisWaitEvent 函式或 NdisMSleep 函式。

在 MiniportInitializeEx 成功傳回之後，迷你埠配接器會處於 Paused 狀態。 NDIS 可以呼叫 MiniportRestart 函式，將迷你埠配接器轉換為執行中狀態。

如果 MiniportInitializeEx 傳回NDIS_STATUS_SUCCESS，驅動程式應該會在 MiniportHaltEx 函式中釋放迷你埠配接器的所有資源。

如果驅動程式傳回NDIS_STATUS_SUCCESS，驅動程式必須呼叫 NdisMSetMiniportAttributes，並在NDIS_MINIPORT_ADAPTER_ATTRIBUTES結構中設定 GeneralAttributes。

如果 MiniportInitializeEx 失敗， MiniportInitializeEx 必須在傳回之前釋放它配置的所有資源，而迷你埠配接器會回到 已停止 狀態。

NDIS 會在 IRQL = PASSIVE_LEVEL呼叫 MiniportInitializeEx 。

例子

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

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

MINIPORT_INITIALIZE MyInitializeEx;

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

_Use_decl_annotations_
NDIS_STATUS
 MyInitializeEx(
    NDIS_HANDLE  NdisMiniportHandle,
    NDIS_HANDLE  MiniportDriverContext,
    PNDIS_MINIPORT_INIT_PARAMETERS  MiniportInitParameters
    )
  {...}

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

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