MINIPORT_PNP_IRP回呼函式 (ndis.h)

發行項
03/05/2024

MiniportPnpIrp 函式可讓迷你埠驅動程序選擇性地管理其隨插即用 (PnP) 資源。 MiniportPnpIrp 本身永遠不會由迷你埠驅動程式直接定義。而是定義為 MiniportFilterResourceRequirements 或 MiniportStartDevice。

如果定義為 MiniportFilterResourceRequirements，此函式可讓迷你埠驅動程式修改裝置的資源需求。如果定義為 MiniportStartDevice，此函式可讓迷你埠驅動程式移除其新增的資源 MiniportFilterResourceRequirements 函 式。

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

語法

MINIPORT_PNP_IRP MiniportPnpIrp;

NDIS_STATUS MiniportPnpIrp(
  [in] NDIS_HANDLE MiniportAddDeviceContext,
  [in] PIRP Irp
)
{...}

參數

[in] MiniportAddDeviceContext

迷你埠驅動程式在 MiniportAddDevice 函式中向NDIS註冊的驅動程式配置內容區域的句柄。

[in] Irp

如果此函式定義為 MiniportFilterResourceRequirements，則此參數是驅動程式要處理的 IRP_MN_FILTER_RESOURCE_REQUIREMENTS 指標。

如果此函式定義為 MiniportStartDevice，則此參數是 IRP_MN_START_DEVICE IRP 的指標。

傳回值

MiniportPnpIrp 會傳回下列其中一個值：

傳回碼	Description
NDIS_STATUS_SUCCESS	迷你埠驅動程式已成功處理啟動裝置要求。
NDIS_STATUS_RESOURCES	迷你埠驅動程式因資源不足而無法處理啟動裝置要求。
NDIS_STATUS_FAILURE	MiniportFilterResourceRequirements 因資源不足而失敗。

備註

MiniportFilterResourceRequirements 備註

MiniportFilterResourceRequirements 函式是選擇性函式。如果迷你埠驅動程序支援 MSI-X，而且至少有一個下列情況成立，則應該註冊此函式：

驅動程式需要能夠變更每個 MSI-X 訊息的中斷親和性。
驅動程式會在中註冊以行為基礎的中斷 MiniportInitializeEx 函式。

若要註冊 MiniportFilterResourceRequirements，請在中指定進入點 NDIS_MINIPORT_PNP_CHARACTERISTICS 結構。

NDIS 會在 NDIS 收到之後呼叫 MiniportFilterResourceRequirements 函式 IRP_MN_FILTER_RESOURCE_REQUIREMENTS 網路適配器的 IRP (NIC) 。 NDIS 會在裝置堆疊中的基礎函式驅動程式完成 IRP 的處理之後，呼叫 MiniportFilterResourceRequirements 。

迷你埠驅動程序必須準備好在MiniportAddDevice函式傳回NDIS_STATUS_SUCCESS之後，立即處理來自MiniportFilterResourceRequirements的IRP_MN_FILTER_RESOURCE_REQUIREMENTS。

迷你埠驅動程式可以為描述 MSI-X 訊息之 CmResourceTypeInterrupt 類型的每個資源設定親和性原則。如果親和性原則要求以特定處理器集為目標，迷你埠驅動程式也會在IO_RESOURCE_DESCRIPTOR結構的Interrupt.TargetedProcessors成員上設定 KAFFINITY 遮罩。

如果 NDIS 6.1 或更新版本的迷你埠驅動程式需要更多訊息中斷資源，它可以在資源清單中新增更多訊息中斷資源。如果操作系統可以提供更多訊息中斷資源，迷你埠配接器會在啟動時收到新增的訊息中斷資源。

清單中每個訊息中斷資源都會獲指派一個訊息號碼，其對應於資源清單中的順序。訊息的編號是從 0 到訊息中斷資源的總數減一。

若要在運行時間將 MSI-X 數據表專案指派給 CPU，迷你埠驅動程式可以呼叫 NdisMConfigMSIXTableEntry 函式。

迷你埠驅動程式可以移除屬於訊息中斷資源之 CmResourceTypeInterrupt 類型的所有資源。驅動程式接著可以在 MiniportInitializeEx 函式中註冊以行為基礎的中斷。如果迷你埠驅動程式未移除這些訊息中斷資源，如果驅動程序嘗試在 MiniportInitializeEx中註冊以行為基礎的中斷，操作系統將會失敗。

若要為新的資源需求清單配置記憶體，請使用 NdisAllocateMemoryWithTagPriority 函式。迷你埠驅動程式可以使用 NdisFreeMemory 函式釋放舊資源需求清單的記憶體。 PnP 管理員會在相關聯的 IRP 完成之後釋放任何驅動程式配置的記憶體。

迷你埠驅動程式不應修改其他資源，例如 CmResourceTypeMemory 和 CmResourceTypePort 資源。迷你埠驅動程序應該避免將新的資源新增至資源清單。不過，迷你埠驅動程式可以新增更多訊息中斷資源。如果迷你埠驅動程式新增更多訊息中斷資源，驅動程式不得從 MiniportStartDevice 函式中移除它們。

如果迷你埠驅動程式從 MiniportFilterResourceRequirements 傳回NDIS_STATUS_RESOURCES或NDIS_STATUS_FAILURE，NDIS 會使用父總線驅動程式所指定的資源需求。

NDIS 可以在 NDIS 呼叫 MiniportRemoveDevice 函式之前多次呼叫 MiniportFilterResourceRequirements。但是，只有在裝置處於停止狀態時，NDIS 才會呼叫 MiniportFilterResourceRequirements 。

NDIS 會在 IRQL = PASSIVE_LEVEL 呼叫 MiniportFilterResourceRequirements 。

MiniportFilterResourceRequirements 範例

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

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

MINIPORT_FILTER_RESOURCE_REQUIREMENTS MyFilterResourceRequirements;

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

_Use_decl_annotations_
NDIS_STATUS
 MyFilterResourceRequirements(
    NDIS_HANDLE  MiniportAddDeviceContext,
    PIRP  Irp
    )
  {...}

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

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

MiniportStartDevice 備註

MiniportStartDevice 是選擇性函式。支援 MSI-X 的迷你埠驅動程式可以在中指定此函式的進入點 NDIS_MINIPORT_PNP_CHARACTERISTICS 結構。當 NDIS 收到來自隨插即用 (PnP) 管理員的要求以啟動裝置時，NDIS 會呼叫 MiniportStartDevice 函式，如果有的話。如果迷你埠驅動程式在中新增資源 MiniportFilterResourceRequirements 函式應該提供 MiniportStartDevice 函式來移除資源。

如果迷你埠驅動程式以基礎總線驅動程式無法辨識資源的方式來修改資源，驅動程序應該提供 MiniportStartDevice 函式來移除資源。如果基礎總線驅動程式無法辨識 MiniportFilterResourceRequirements 中新增的迷你埠驅動程序資源，啟動裝置要求可能會失敗。如果迷你埠驅動程式新增訊息中斷資源，則不得將其從 MiniportStartDevice 中移除。

NDIS 會先呼叫 MiniportStartDevice ，再將啟動裝置要求轉送至基礎驅動程式。如果基礎驅動程式成功完成要求，NDIS 會呼叫 MiniportInitializeEx 函式來初始化迷你埠配接器。

NDIS 在 IRQL = PASSIVE_LEVEL 呼叫 MiniportStartDevice 。

MiniportStartDevice 範例

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

例如，若要定義名為「 MyStartDevice」的 MiniportStartDevice 函式，請使用 MINIPORT_START_DEVICE 類型，如下列程式碼範例所示：

MINIPORT_START_DEVICE MyStartDevice;

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

_Use_decl_annotations_
NDIS_STATUS
 MyStartDevice(
    NDIS_HANDLE  MiniportAddDeviceContext,
    PIRP  Irp
    )
  {...}

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

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