MINIPORT_PNP_IRP funzione di callback (ndis.h)

Articolo
08/07/2023

La funzione MiniportPnpIrp consente a un driver miniport di gestire facoltativamente le risorse Plug and Play (PnP). MiniportPnpIrp stesso non è mai definito direttamente dai driver miniport. Viene invece definito come MiniportFilterResourceRequirements o MiniportStartDevice.

Se definito come MiniportFilterResourceRequirements, questa funzione consente a un driver miniport di modificare i requisiti delle risorse per un dispositivo. Se definito come MiniportStartDevice, questa funzione consente al driver miniport di rimuovere le risorse aggiunte nel Funzione MiniportFilterResourceRequirements .

Nota È necessario dichiarare questa funzione usando il tipo MINIPORT_FILTER_RESOURCE_REQUIREMENTS o il tipo di MINIPORT_START_DEVICE . Per altre informazioni, vedere la sezione Esempi seguente.

Sintassi

MINIPORT_PNP_IRP MiniportPnpIrp;

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

Parametri

[in] MiniportAddDeviceContext

Handle per un'area di contesto allocata dal driver registrato con NDIS nella funzione MiniportAddDevice .

[in] Irp

Se questa funzione è definita come MiniportFilterResourceRequirements, questo parametro è un puntatore al IRP_MN_FILTER_RESOURCE_REQUIREMENTS per consentire al driver di gestire.

Se questa funzione è definita come MiniportStartDevice, questo parametro è un puntatore a un IRP_MN_START_DEVICE IRP.

Valore restituito

MiniportPnpIrp restituisce uno dei valori seguenti:

Codice restituito	Descrizione
NDIS_STATUS_SUCCESS	Il driver miniport ha gestito correttamente la richiesta del dispositivo di avvio.
NDIS_STATUS_RESOURCES	Il driver miniport non è riuscito a gestire la richiesta di avvio del dispositivo a causa di risorse ridotte.
NDIS_STATUS_FAILURE	MiniportFilterResourceRequirements non è riuscito per motivi diversi da risorse insufficienti.

Commenti

MiniportFilterResourceRequirements Osservazioni

La funzione MiniportFilterResourceRequirements è una funzione facoltativa. I driver Miniport devono registrare questa funzione se supportano MSI-X e almeno uno dei seguenti è vero:

Il driver richiede la possibilità di modificare l'affinità di interruzione per ogni messaggio MSI-X.
Il driver si registrerà per gli interrupt basati su linea nel Funzione MiniportInitializeEx .

Per registrare MiniportFilterResourceRequirements, specificare il punto di ingresso in NDIS_MINIPORT_PNP_CHARACTERISTICS struttura.

NDIS chiama la funzione MiniportFilterResourceRequirements dopo che NDIS riceve un IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRP per una scheda di interfaccia di rete.IRP for a network interface card (NIC). NDIS chiama MiniportFilterResourceRequirements dopo che i driver di funzione sottostanti nello stack di dispositivi hanno completato l'elaborazione di IRP.

Il driver miniport deve essere preparato per gestire IRP_MN_FILTER_RESOURCE_REQUIREMENTS da MiniportFilterResourceRequirements immediatamente dopo che la funzione MiniportAddDevice restituisce NDIS_STATUS_SUCCESS.

Un driver miniport può impostare un criterio di affinità per ogni risorsa di tipo CmResourceTypeInterrupt che descrive un messaggio MSI-X. Se un criterio di affinità richiede la destinazione per un set specifico di processori, il driver miniport imposta anche una maschera KAFFINITY sul membro Interrupt.TargetedProcessors nella struttura IO_RESOURCE_DESCRIPTOR .

Se un driver miniport NDIS 6.1 o versione successiva richiede più risorse di interruzione dei messaggi, può aggiungere altre risorse di interrupt dei messaggi all'elenco delle risorse. Se il sistema operativo può fornire più risorse di interruzione dei messaggi, l'adattatore miniport riceve le risorse di interrupt del messaggio aggiunte all'avvio.

A ogni risorsa di interrupt del messaggio nell'elenco viene assegnato un numero di messaggio corrispondente all'ordine in cui è incluso nell'elenco delle risorse. I messaggi vengono numerati da 0 al numero totale di risorse di interruzione del messaggio meno uno.

Per assegnare una voce di tabella MSI-X a una CPU in fase di esecuzione, il driver miniport può chiamare il Funzione NdisMConfigMSIXTableEntry .

Un driver miniport può rimuovere tutte le risorse di tipo CmResourceTypeInterrupt che sono risorse di interrupt del messaggio. Il driver può quindi registrarsi per gli interrupt basati su riga nella funzione MiniportInitializeEx . Se il driver miniport non rimuove queste risorse di interrupt del messaggio, il sistema operativo avrà esito negativo se il driver tenta di registrare l'interrupt basato su riga in MiniportInitializeEx.

Per allocare memoria per un nuovo elenco di requisiti delle risorse, usare Funzione NdisAllocateMemoryWithTagPriority . Il driver miniport può liberare la memoria per l'elenco dei requisiti di risorse precedenti con la funzione NdisFreeMemory . Il gestore PnP libera qualsiasi memoria allocata dal driver dopo il completamento dell'IRP associato.

I driver Miniport non devono modificare altre risorse, ad esempio le risorse CmResourceTypeMemory e CmResourceTypePort . I driver Miniport devono evitare di aggiungere una nuova risorsa all'elenco di risorse. Tuttavia, i driver miniport possono aggiungere altre risorse di interrupt dei messaggi. Se il driver miniport aggiunge altre risorse di interruzione dei messaggi, il driver non deve rimuoverle dalla funzione MiniportStartDevice .

Se un driver miniport restituisce NDIS_STATUS_RESOURCES o NDIS_STATUS_FAILURE da MiniportFilterResourceRequirements, NDIS userà i requisiti di risorsa come specificato dal driver del bus padre.

NDIS può chiamare MiniportFilterResourceRequirements più volte prima che NDIS chiami la funzione MiniportRemoveDevice . Ma NDIS chiama MiniportFilterResourceRequirements solo quando un dispositivo è nello stato arrestato.

NDIS chiama MiniportFilterResourceRequirements in IRQL = PASSIVE_LEVEL.

Esempio di MiniportFilterResourceRequirements

Per definire una funzione MiniportFilterResourceRequirements , è prima necessario fornire una dichiarazione di funzione che identifica il tipo di funzione che si sta definendo. Windows fornisce un set di tipi di funzione per i driver. La dichiarazione di una funzione con i tipi di funzione consente di eseguire l'analisi del codice per i driver, l'SDV ( Static Driver Verifier ) e altri strumenti di verifica rilevano gli errori ed è un requisito per la scrittura dei driver per il sistema operativo Windows.

Ad esempio, per definire una funzione MiniportFilterResourceRequirements denominata "MyFilterResourceRequirements", usare il tipo MINIPORT_FILTER_RESOURCE_REQUIREMENTS come illustrato nell'esempio di codice seguente:

MINIPORT_FILTER_RESOURCE_REQUIREMENTS MyFilterResourceRequirements;

Implementare quindi la funzione come segue:

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

Il tipo di funzione MINIPORT_FILTER_RESOURCE_REQUIREMENTS è definito nel file di intestazione Ndis.h. Per identificare in modo più accurato gli errori quando si eseguono gli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione Use_decl_annotations alla definizione della funzione. L'annotazione Use_decl_annotations assicura che vengano utilizzate le annotazioni applicate al tipo di funzione MINIPORT_FILTER_RESOURCE_REQUIREMENTS nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo di funzione per i driver NDIS.

Per informazioni sulle Use_decl_annotations, vedere Annotazione del comportamento della funzione.

MiniportStartDevice Osservazioni

MiniportStartDevice è una funzione facoltativa. I driver miniport che supportano MSI-X possono specificare un punto di ingresso per questa funzione in NDIS_MINIPORT_PNP_CHARACTERISTICS struttura. Quando NDIS riceve una richiesta dal gestore di Plug and Play (PnP) per avviare un dispositivo, NDIS chiama la funzione MiniportStartDevice, se presente. Se un driver miniport aggiunge nuove risorse in La funzione MiniportFilterResourceRequirements deve fornire una funzione MiniportStartDevice per rimuovere le risorse.

Se un driver miniport modifica le risorse in modo che un driver del bus sottostante non possa riconoscere le risorse, il driver deve fornire una funzione MiniportStartDevice per rimuovere le risorse. Un driver del bus sottostante potrebbe non riuscire a richiedere un dispositivo di avvio se non riconosce le risorse aggiunte da un driver miniportFilterResourceRequirements. Se il driver miniport aggiunge risorse di interruzione dei messaggi, non deve rimuoverle da MiniportStartDevice.

NDIS chiama MiniportStartDevice prima di inoltrare la richiesta del dispositivo di avvio ai driver sottostanti. Se un driver sottostante completa correttamente la richiesta, NDIS chiama la funzione MiniportInitializeEx per inizializzare l'adattatore miniport.

NDIS chiama MiniportStartDevice in IRQL = PASSIVE_LEVEL.

Esempio di MiniportStartDevice

Per definire una funzione MiniportStartDevice , è innanzitutto necessario fornire una dichiarazione di funzione che identifica il tipo di funzione che si sta definendo. Windows fornisce un set di tipi di funzione per i driver. La dichiarazione di una funzione con i tipi di funzione consente di eseguire l'analisi del codice per i driver, l'SDV ( Static Driver Verifier ) e altri strumenti di verifica rilevano gli errori ed è un requisito per la scrittura dei driver per il sistema operativo Windows.

Ad esempio, per definire una funzione MiniportStartDevice denominata "MyStartDevice", usare il tipo di MINIPORT_START_DEVICE come illustrato nell'esempio di codice seguente:

MINIPORT_START_DEVICE MyStartDevice;

Implementare quindi la funzione come segue:

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

Il tipo di funzione MINIPORT_START_DEVICE è definito nel file di intestazione Ndis.h. Per identificare in modo più accurato gli errori quando si eseguono gli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione Use_decl_annotations alla definizione della funzione. L'annotazione Use_decl_annotations garantisce che vengano utilizzate le annotazioni applicate al tipo di funzione MINIPORT_START_DEVICE nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo di funzione per i driver NDIS.

Per informazioni sulle Use_decl_annotations, vedere Annotazione del comportamento della funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Supportato in NDIS 6.0 e versioni successive.
Piattaforma di destinazione	Windows
Intestazione	ndis.h (include Ndis.h)
IRQL	PASSIVE_LEVEL