MINIPORT_RESET fonction de rappel (ndis.h)

Article
08/07/2023

Avertissement

Les fonctions de rappel MiniportResetEx et MiniportCheckForHangEx sont déconseillées pour tous les pilotes NDIS 6.83 et versions ultérieures. Pour plus d’informations, consultez Opérations de vérification et de réinitialisation dans NDIS 6.83 et versions ultérieures.

NDIS appelle la fonction MiniportResetEx d’un pilote miniport NDIS pour lancer une réinitialisation d’une interface réseau carte (NIC). Pour plus d’informations, consultez Miniport Adapter Check-for-Hang and Reset Operations et Miniport Driver Hardware Reset.

Note Un pilote miniport NDIS peut déclarer cette fonction à l’aide du type MINIPORT_RESET .

Syntaxe

MINIPORT_RESET MiniportReset;

NDIS_STATUS MiniportReset(
  [in]  NDIS_HANDLE MiniportAdapterContext,
  [out] PBOOLEAN AddressingReset
)
{...}

Paramètres

[in] MiniportAdapterContext

Handle à une zone de contexte que le pilote miniport a allouée dans sa fonction MiniportInitializeEx . Le pilote miniport utilise cette zone de contexte pour conserver les informations d’état d’un adaptateur miniport.

[out] AddressingReset

Pointeur vers une variable booléenne. Le pilote miniport définit cette variable sur TRUE si NDIS doit appeler la fonction MiniportOidRequest pour restaurer l’adressage et d’autres paramètres de configuration aux valeurs actuelles. Pour plus d’informations, consultez Réinitialisation matérielle.

Valeur retournée

MiniportResetEx peut retourner l’une des valeurs status suivantes :

Code de retour	Description
NDIS_STATUS_SUCCESS	MiniportResetEx a correctement réinitialisé l’adaptateur miniport à un état opérationnel.
NDIS_STATUS_PENDING	Le pilote termine l’opération de réinitialisation de manière asynchrone en appelant la fonction NdisMResetComplete lorsque l’opération est terminée.
NDIS_STATUS_RESET_IN_PROGRESS	MiniportResetEx a déterminé que l’adaptateur miniport était en cours de réinitialisation, donc cet appel est superflu.
NDIS_STATUS_SOFT_ERRORS	MiniportResetEx a correctement réinitialisé l’adaptateur miniport, mais une erreur récupérable s’est produite pendant l’opération. MiniportResetEx doit avoir appelé la fonction NdisWriteErrorLogEntry avec plus d’informations sur l’erreur.
NDIS_STATUS_HARD_ERRORS	MiniportResetEx a essayé de réinitialiser l’adaptateur miniport, mais une erreur irrécupérable s’est produite pendant l’opération. MiniportResetEx doit avoir appelé NdisWriteErrorLogEntry avec plus d’informations sur l’erreur.

Remarques

Un pilote spécifie le point d’entrée MiniportResetEx lorsqu’il appelle le Fonction NdisMRegisterMiniportDriver .

MiniportResetEx n’est pas obligatoire pour les pilotes intermédiaires.

MiniportResetEx peut réinitialiser les paramètres de l’adaptateur miniport. Si une réinitialisation provoque une modification de l’adresse de station de l’adaptateur miniport, le pilote miniport restaure automatiquement la valeur précédente de l’adresse de la station une fois la réinitialisation terminée. Les masques de multidiffusion ou d’adressage fonctionnels, réinitialisés par le matériel, n’ont pas besoin d’être réinitialisés dans cette fonction.

Si une opération de réinitialisation modifie d’autres informations, telles que la multidiffusion ou les informations d’adressage fonctionnelles, MiniportResetEx doit définir la variable dans AddressingReset sur TRUE avant qu’elle ne retourne. Cela oblige NDIS à appeler la fonction MiniportOidRequest pour restaurer les informations. NDIS restaure également la liste de modèles Wake on the LAN (WoL) en appelant OID_PNP_ADD_WAKE_UP_PATTERN. Le pilote doit libérer la liste de modèles WoL de son contexte d’adaptateur, car la liste matérielle est déjà réinitialisée.

NDIS n’abandonnera pas les demandes d’OID en attente ni n’enverra de demandes. Si le pilote peut exécuter en toute sécurité l’OID en attente ou envoyer des demandes après une réinitialisation, le pilote peut conserver l’OID en attente ou envoyer des requêtes jusqu’à la fin de l’opération de réinitialisation. Sinon, le pilote doit terminer l’OID en attente ou envoyer des requêtes en appelant le NdisMOidRequestComplete ou NdisMSendNetBufferListsComplete fonctionnent respectivement avant que MiniportResetEx ne retourne.

Note À compter de NDIS 6.30, le pilote miniport ne doit pas contenir d’OID en attente ni envoyer de requêtes tant qu’une fois l’opération de réinitialisation terminée. Au lieu de cela, le pilote doit effectuer ces demandes en attente en appelant respectivement les fonctions NdisMOidRequestComplete ou NdisMSendNetBufferListsComplete avant que l’opération de réinitialisation ne soit terminée. Si le pilote termine l’opération de réinitialisation de manière asynchrone, il doit terminer l’OID en attente et envoyer des requêtes avant que le pilote appelle NdisMResetComplete.

Un pilote miniport ne doit pas appeler la fonction NdisMIndicateStatusEx pour signaler le début et la fin de chaque opération de réinitialisation. NDIS avertit les pilotes de protocole lié lorsqu’une réinitialisation commence et se termine.

Si MiniportResetEx doit attendre les changements d’état de l’adaptateur miniport pendant les opérations de réinitialisation, il peut appeler la fonction NdisStallExecution . Toutefois, un
La fonction MiniportResetEx ne doit pas appeler NdisStallExecution avec un intervalle de temps supérieur à 50 microsecondes. Si le pilote doit attendre plus de 50 microsecondes (ou s’il interroge), il doit définir un minuteur à la place et retourner NDIS_STATUS_PENDING.

Si MiniportResetEx retourne NDIS_STATUS_PENDING, le pilote doit terminer la réinitialisation en appelant la fonction NdisMResetComplete .

Si un adaptateur miniport est à l’état MediaConnectStateConnected et que son état change en raison d’une réinitialisation, y compris une modification de l’état MediaConnectStateUnknown, le pilote miniport doit signaler le changement d’état avec une NDIS_STATUS_LINK_STATE status indication. Le pilote miniport doit également indiquer une indication MediaConnectStateConnected status lorsque le lien est rétabli après la réinitialisation.

MiniportResetEx peut être préempté par une interruption.

NDIS appelle régulièrement la fonction MiniportCheckForHangEx pour déterminer s’il doit appeler MiniportResetEx. Le délai d’attente par défaut pour appeler MiniportCheckForHangEx est de 2 secondes. Si cette valeur par défaut est trop courte, un pilote miniport peut définir une valeur CheckForHangTimeInSeconds plus grande lors de l’appel du
Fonction NdisMSetMiniportAttributes pendant l’initialisation. Pour plus d’informations, consultez Miniport Adapter Check-for-Hang and Reset Operations.

NDIS ne peut pas déterminer si une carte réseau a cessé de répondre pour les opérations de réception. Pour gérer ce type de défaillance, la fonction MiniportCheckForHangEx peut surveiller les opérations de réception et, si nécessaire, retourner TRUE pour forcer une réinitialisation. Un miniport peut également demander une réinitialisation en appelant NdisMResetMiniport.

NDIS appelle MiniportResetEx à IRQL <= DISPATCH_LEVEL.

Exemples

Pour définir une fonction MiniportResetEx , 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, le vérificateur de pilotes statique (SDV) et d’autres outils de vérification de trouver les erreurs, et 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 MiniportResetEx nommée « MyResetEx », utilisez le type MINIPORT_RESET comme indiqué dans cet exemple de code :

MINIPORT_RESET MyResetEx;

Ensuite, implémentez votre fonction comme suit :

_Use_decl_annotations_
NDIS_STATUS
 MyResetEx(
    NDIS_HANDLE  MiniportAdapterContext,
    PBOOLEAN  AddressingReset
    )
  {...}

Le type de fonction MINIPORT_RESET 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_RESET 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	<= DISPATCH_LEVEL