MINIPORT_PNP_IRP fonction de rappel (ndis.h)

Article
02/26/2024

La fonction MiniportPnpIrp permet à un pilote miniport de gérer éventuellement ses ressources Plug-and-Play (PnP). MiniportPnpIrp lui-même n’est jamais défini par les pilotes de miniport directement. Au lieu de cela, il est défini comme MiniportFilterResourceRequirements ou MiniportStartDevice.

Si elle est définie comme MiniportFilterResourceRequirements, cette fonction permet à un pilote miniport de modifier les besoins en ressources d’un appareil. Si elle est définie comme MiniportStartDevice, cette fonction permet au pilote miniport de supprimer les ressources qu’il a ajoutées dans le Fonction MiniportFilterResourceRequirements .

Note Vous devez déclarer cette fonction à l’aide du type MINIPORT_FILTER_RESOURCE_REQUIREMENTS ou du type MINIPORT_START_DEVICE . Pour plus d’informations, consultez la section Exemples suivante.

Syntaxe

MINIPORT_PNP_IRP MiniportPnpIrp;

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

Paramètres

[in] MiniportAddDeviceContext

Handle pour une zone de contexte allouée par le pilote que le pilote miniport a inscrite auprès de NDIS dans la fonction MiniportAddDevice .

[in] Irp

Si cette fonction est définie en tant que MiniportFilterResourceRequirements, ce paramètre est un pointeur vers le IRP_MN_FILTER_RESOURCE_REQUIREMENTS que le pilote doit gérer.

Si cette fonction est définie comme MiniportStartDevice, ce paramètre est un pointeur vers un IRP IRP_MN_START_DEVICE .

Valeur retournée

MiniportPnpIrp retourne l’une des valeurs suivantes :

Code de retour	Description
NDIS_STATUS_SUCCESS	Le pilote miniport a géré la demande de démarrage de périphérique avec succès.
NDIS_STATUS_RESOURCES	Le pilote miniport n’a pas pu gérer la demande de démarrage du périphérique en raison de faibles ressources.
NDIS_STATUS_FAILURE	Les miniportFilterResourceRequirements ont échoué pour des raisons autres que des ressources insuffisantes.

Remarques

Remarques sur MiniportFilterResourceRequirements

La fonction MiniportFilterResourceRequirements est une fonction facultative. Les pilotes Miniport doivent inscrire cette fonction s’ils prennent en charge MSI-X et qu’au moins l’une des conditions suivantes est vraie :

Le pilote nécessite la possibilité de modifier l’affinité d’interruption pour chaque message MSI-X.
Le pilote s’inscrit pour les interruptions basées sur les lignes dans le Fonction MiniportInitializeEx .

Pour inscrire MiniportFilterResourceRequirements, spécifiez le point d’entrée dans le NDIS_MINIPORT_PNP_CHARACTERISTICS structure.

NDIS appelle la fonction MiniportFilterResourceRequirements après que NDIS a reçu un IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRP pour une interface réseau carte (NIC). NDIS appelle MiniportFilterResourceRequirements une fois que les pilotes de fonction sous-jacents dans la pile de périphériques ont terminé le traitement de l’IRP.

Le pilote miniport doit être prêt à gérer IRP_MN_FILTER_RESOURCE_REQUIREMENTS à partir de MiniportFilterResourceRequirements immédiatement après que la fonction MiniportAddDevice a retourné NDIS_STATUS_SUCCESS.

Un pilote miniport peut définir une stratégie d’affinité pour chaque ressource de type CmResourceTypeInterrupt qui décrit un message MSI-X. Si une stratégie d’affinité demande un ciblage pour un ensemble spécifique de processeurs, le pilote miniport définit également un masque KAFFINITY au niveau du membre Interrupt.TargetedProcessors dans la structure IO_RESOURCE_DESCRIPTOR .

Si un pilote miniport NDIS 6.1 ou ultérieur nécessite davantage de ressources d’interruption de message, il peut ajouter d’autres ressources d’interruption de message à la liste des ressources. Si le système d’exploitation peut fournir davantage de ressources d’interruption de message, l’adaptateur miniport reçoit les ressources d’interruption de message ajoutées au démarrage.

Chaque ressource d’interruption de message de la liste se voit attribuer un numéro de message qui correspond à l’ordre qu’elle a dans la liste des ressources. Les messages sont numérotés entre 0 et le nombre total de ressources d’interruption de message moins un.

Pour affecter une entrée de table MSI-X à un processeur au moment de l’exécution, le pilote miniport peut appeler le Fonction NdisMConfigMSIXTableEntry .

Un pilote miniport peut supprimer toutes les ressources de type CmResourceTypeInterrupt qui sont des ressources d’interruption de message. Le pilote peut ensuite s’inscrire pour les interruptions basées sur les lignes dans la fonction MiniportInitializeEx . Si le pilote miniport ne supprime pas ces ressources d’interruption de message, le système d’exploitation échoue si le pilote tente d’inscrire l’interruption basée sur les lignes dans MiniportInitializeEx.

Pour allouer de la mémoire à une nouvelle liste de ressources requises, utilisez le Fonction NdisAllocateMemoryWithTagPriority . Le pilote miniport peut libérer de la mémoire pour l’ancienne liste des besoins en ressources avec la fonction NdisFreeMemory . Le gestionnaire PnP libère toute mémoire allouée au pilote une fois l’IRP associée terminée.

Les pilotes miniport ne doivent pas modifier d’autres ressources, telles que les ressources CmResourceTypeMemory et CmResourceTypePort . Les pilotes miniport doivent éviter d’ajouter une nouvelle ressource à la liste des ressources. Toutefois, les pilotes miniport peuvent ajouter d’autres ressources d’interruption de message. Si le pilote miniport ajoute des ressources d’interruption de message, il ne doit pas les supprimer de la fonction MiniportStartDevice .

Si un pilote miniport retourne NDIS_STATUS_RESOURCES ou NDIS_STATUS_FAILURE à partir de MiniportFilterResourceRequirements, NDIS utilise les exigences de ressources spécifiées par le pilote de bus parent.

NDIS peut appeler MiniportFilterResourceRequirements plusieurs fois avant que NDIS appelle la fonction MiniportRemoveDevice . Toutefois, NDIS appelle MiniportFilterResourceRequirements uniquement lorsqu’un appareil est à l’état arrêté.

NDIS appelle MiniportFilterResourceRequirements à l’adresse IRQL = PASSIVE_LEVEL.

Exemple MiniportFilterResourceRequirements

Pour définir une fonction MiniportFilterResourceRequirements , vous devez d’abord fournir une déclaration de fonction qui identifie le type de fonction que vous définissez. Windows fournit un ensemble de types de fonctions pour les pilotes. La déclaration d’une fonction à l’aide des types de fonction permet à l’analyse du code pour les pilotes, au vérificateur de pilotes statiques (SDV) et à d’autres outils de vérification de trouver des erreurs. Il s’agit d’une exigence pour l’écriture de pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une fonction MiniportFilterResourceRequirements nommée « MyFilterResourceRequirements », utilisez le type MINIPORT_FILTER_RESOURCE_REQUIREMENTS comme indiqué dans cet exemple de code :

MINIPORT_FILTER_RESOURCE_REQUIREMENTS MyFilterResourceRequirements;

Ensuite, implémentez votre fonction comme suit :

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

Le type de fonction MINIPORT_FILTER_RESOURCE_REQUIREMENTS est défini dans le fichier d’en-tête Ndis.h. Pour identifier plus précisément les erreurs lors de l’exécution des outils d’analyse du code, veillez à ajouter l’annotation Use_decl_annotations à votre définition de fonction. L’annotation Use_decl_annotations garantit que les annotations appliquées au type de fonction MINIPORT_FILTER_RESOURCE_REQUIREMENTS dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes NDIS.

Pour plus d’informations sur Use_decl_annotations, consultez Annotating Function Behavior.

Remarques sur MiniportStartDevice

MiniportStartDevice est une fonction facultative. Les pilotes Miniport qui prennent en charge MSI-X peuvent spécifier un point d’entrée pour cette fonction dans le NDIS_MINIPORT_PNP_CHARACTERISTICS structure. Lorsque NDIS reçoit une demande du gestionnaire Plug-and-Play (PnP) pour démarrer un appareil, NDIS appelle la fonction MiniportStartDevice, le cas échéant. Si un pilote miniport ajoute de nouvelles ressources dans le La fonction MiniportFilterResourceRequirements doit fournir une fonction MiniportStartDevice pour supprimer les ressources.

Si un pilote miniport modifie des ressources de telle sorte qu’un pilote de bus sous-jacent ne puisse pas reconnaître les ressources, le pilote doit fournir une fonction MiniportStartDevice pour supprimer les ressources. Un pilote de bus sous-jacent peut échouer à une demande de périphérique de démarrage s’il ne reconnaît pas les ressources qu’un pilote miniport a ajoutées dans MiniportFilterResourceRequirements. Si le pilote miniport ajoute des ressources d’interruption de message, il ne doit pas les supprimer de MiniportStartDevice.

NDIS appelle MiniportStartDevice avant de transférer la demande de démarrage de l’appareil aux pilotes sous-jacents. Si un pilote sous-jacent termine correctement la demande, NDIS appelle la fonction MiniportInitializeEx pour initialiser l’adaptateur miniport.

NDIS appelle MiniportStartDevice à IRQL = PASSIVE_LEVEL.

Exemple MiniportStartDevice

Pour définir une fonction MiniportStartDevice , vous devez d’abord fournir une déclaration de fonction qui identifie le type de fonction que vous définissez. Windows fournit un ensemble de types de fonctions pour les pilotes. La déclaration d’une fonction à l’aide des types de fonction permet à l’analyse du code pour les pilotes, au vérificateur de pilotes statiques (SDV) et à d’autres outils de vérification de trouver des erreurs. Il s’agit d’une exigence pour l’écriture de pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une fonction MiniportStartDevice nommée « MyStartDevice », utilisez le type MINIPORT_START_DEVICE comme indiqué dans cet exemple de code :

MINIPORT_START_DEVICE MyStartDevice;

Ensuite, implémentez votre fonction comme suit :

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

Le type de fonction MINIPORT_START_DEVICE est défini dans le fichier d’en-tête Ndis.h. Pour identifier plus précisément les erreurs lors de l’exécution des outils d’analyse du code, veillez à ajouter l’annotation Use_decl_annotations à votre définition de fonction. L’annotation Use_decl_annotations garantit que les annotations appliquées au type de fonction MINIPORT_START_DEVICE dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes NDIS.

Pour plus d’informations sur Use_decl_annotations, consultez Annotating Function Behavior.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Pris en charge dans NDIS 6.0 et versions ultérieures.
Plateforme cible	Windows
En-tête	ndis.h (inclure Ndis.h)
IRQL	PASSIVE_LEVEL