MINIPORT_INITIALIZE fonction de rappel (ndis.h)

Article
03/08/2023

NDIS appelle la fonction MiniportInitializeEx d’un pilote miniport pour initialiser une carte miniport pour les opérations d’E/S réseau.

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

Syntaxe

MINIPORT_INITIALIZE MiniportInitialize;

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

Paramètres

[in] NdisMiniportHandle

Handle fourni par NDIS qui identifie l’adaptateur miniport que le pilote miniport doit initialiser.

[in] MiniportDriverContext

Handle vers une zone de contexte allouée par le pilote où le pilote conserve les informations d’état et de configuration. Le pilote miniport a passé cette zone de contexte au Fonction NdisMRegisterMiniportDriver .

[in] MiniportInitParameters

Pointeur vers un NDIS_MINIPORT_INIT_PARAMETERS structure qui définit les paramètres d’initialisation de l’adaptateur miniport.

Valeur retournée

MiniportInitializeEx peut retourner l’une des valeurs status suivantes :

Code de retour	Description
NDIS_STATUS_SUCCESS	MiniportInitializeEx a configuré et configuré l’adaptateur miniport, et alloué toutes les ressources dont le pilote doit disposer pour effectuer des opérations d’E/S réseau.
NDIS_STATUS_NOT_ACCEPTED	MiniportInitializeEx n’a pas pu obtenir que l’adaptateur miniport accepte les paramètres de configuration que MiniportInitializeEx a obtenus à partir du Registre.
NDIS_STATUS_RESOURCES	MiniportInitializeEx n’a pas pu allouer de ressources pour effectuer des opérations d’E/S réseau. MiniportInitializeEx doit appeler la fonction NdisWriteErrorLogEntry pour identifier le conflit de ressources (par exemple, plage de ports d’E/S, vecteur d’interruption, plage de mémoire de l’appareil, le cas échéant). La fourniture d’un enregistrement de journal des erreurs donne à l’utilisateur ou à l’administrateur système des informations qui peuvent être utilisées pour reconfigurer l’ordinateur afin d’éviter de tels conflits de ressources matérielles.
NDIS_STATUS_FAILURE	MiniportInitializeEx a échoué pour des raisons autres que celles de la liste précédente. Le pilote doit appeler NdisWriteErrorLogEntry avec des paramètres qui spécifient la raison de l’échec.

Remarques

NDIS appelle MiniportInitializeEx dans le cadre d’une opération PnP système. Les pilotes spécifient le point d’entrée MiniportInitializeEx en appelant le Fonction NdisMRegisterMiniportDriver de la routine DriverEntry . NDIS peut appeler MiniportInitializeEx après le retour de DriverEntry . Pour plus d’informations, consultez DriverEntry of NDIS Miniport Drivers.

Pour les pilotes intermédiaires NDIS, NDIS peut appeler MiniportInitializeEx dans le contexte du Fonction NdisIMInitializeDeviceInstanceEx ou après son retour. La fonction ProtocolBindAdapterEx d’un tel pilote appelle généralement NdisIMInitializeDeviceInstanceEx.

Les pilotes peuvent s’inscrire en tant que pilote miniport combiné et pilote intermédiaire (voir NdisMRegisterMiniportDriver). Un tel pilote miniport-intermédiaire fonctionne de la même façon qu’un pilote intermédiaire superposé à un pilote miniport physique. Pour chaque périphérique virtuel ou physique instance d’un pilote miniport intermédiaire, si la clé de Registre IMMiniport est définie sur DWORD :0x0000001, NDIS appelle la fonction MiniportInitializeEx que le pilote a inscrite pour l’appareil virtuel. Sinon, NDIS appelle la fonction MiniportInitializeEx du pilote que le pilote a inscrite pour l’appareil physique.

Tant que MiniportInitializeEx n’est pas retourné, NDIS n’envoie aucune demande pour l’initialisation de l’adaptateur miniport. L’adaptateur miniport est à l’état d’initialisation .

Pour obtenir des informations de configuration pour l’adaptateur miniport, un pilote appelle les fonctions NdisOpenConfigurationEx et NdisReadConfiguration . Le pilote peut appeler la fonction NdisMGetBusData pour obtenir des informations spécifiques au bus.

Les pilotes miniport doivent appeler le Fonction NdisMSetMiniportAttributes et fournir un NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES structure qui contient les attributs suivants :

Handle d’une zone de contexte allouée par le pilote.
Indicateurs d’attributs appropriés.
Intervalle de délai d’attente pour appeler son Fonction MiniportCheckForHangEx .
Type de l'interface.

Le pilote miniport transmet NdisMSetMiniportAttribute une poignée au membre MiniportAdapterContext de NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES. Le pilote conserve les informations d’état pour l’adaptateur miniport spécifié dans cette zone de contexte. NDIS transmet ce handle en tant que paramètre d’entrée à d’autres fonctions MiniportXxx .

Les pilotes miniport doivent définir les attributs dans le NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES structure après avoir défini les attributs d’inscription dans la structure NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES et avant de définir des attributs supplémentaires.

MiniportInitializeEx peut également allouer des ressources telles que les suivantes :

Mémoire de pool non paginée
pools de structures NET_BUFFER et NET_BUFFER_LIST
Verrous de rotation
Minuteries
Ports d’E/S
DMA
Mémoire partagée
Interruptions

Si le pilote indique reçoit avec le NdisMIndicateReceiveNetBufferLists , la fonction MiniportInitializeEx doit appeler le NdisAllocateNetBufferListPool et Fonctions NdisAllocateNetBufferPool et enregistrez les handles retournés par ces fonctions NDIS. En règle générale, les données réseau que le pilote indique par la suite avec NdisMIndicateReceiveNetBufferLists référencent des structures qui ont été allouées avec le Fonction NdisAllocateNetBufferAndNetBufferList . Un pilote peut également utiliser des structures qui ont été allouées avec le NdisAllocateNetBuffer, et Fonctions NdisAllocateNetBufferList .

Si les fonctions de pilote, autres que la fonction MiniportInterrupt , partagent des ressources, MiniportInitializeEx doit appeler la fonction NdisAllocateSpinLock pour configurer les verrous de rotation nécessaires pour synchroniser l’accès à ces ressources partagées. Les ressources que d’autres fonctions de pilote partagent avec MiniportInterrupt, telles que les registres de carte réseau, sont protégées par l’objet d’interruption que le pilote a configuré avec le Fonction NdisMRegisterInterruptEx . Les fonctions de pilote accèdent à ces ressources en appelant le Fonction NdisMSynchronizeWithInterruptEx .

MiniportInitializeEx peut appeler la fonction NdisAllocateTimerObject avec une fonction NetTimerCallback fournie par le pilote et un pointeur vers la mémoire allouée au pilote pour un objet minuteur. Les pilotes peuvent configurer plusieurs fonctions NetTimerCallback , chacune avec son propre objet de minuteur. Un pilote peut appeler la fonction NdisSetTimerObject pour activer une fonction NetTimerCallback périodique. Un pilote peut également appeler la fonction NdisSetTimerObject pour activer une fonction NetTimerCallback à usage unique.

MiniportInitializeEx doit appeler le Fonction NdisMSetMiniportAttributes avant d’appeler n’importe quelle fonction NdisMXxx , telle que les fonctions NdisMRegisterIoPortRange ou NdisMMapIoSpace , qui réclame des ressources matérielles pour l’adaptateur miniport. MiniportInitializeEx doit appeler NdisMSetMiniportAttributes avant d’essayer d’allouer des ressources pour les opérations DMA.

Si l’appareil prend en charge la DMA master bus, MiniportInitializeEx doit appeler le Fonction NdisMRegisterScatterGatherDma après avoir appelé NdisMSetMiniportAttributes et avant d’appeler le Fonction NdisMAllocateSharedMemory . Si l’appareil prend en charge DMA subordonné, MiniportInitializeEx doit appeler NdisMSetMiniportAttributes avant d’appeler le Fonction NdisMRegisterDmaChannel .

Après que MiniportInitializeEx appelle le NdisMRegisterInterruptEx , NDIS peut appeler la fonction MiniportInterrupt du pilote. NDIS appelle MiniportInterrupt si la carte réseau génère une interruption ou si tout autre appareil avec lequel la carte réseau partage une interruption génère une interruption. Notez qu’un pilote miniport peut obtenir une interruption dès qu’il appelle NdisMRegisterInterruptEx et continue d’obtenir des interruptions jusqu’à son appel à La fonction NdisMDeregisterInterruptEx retourne.

MiniportInitializeEx doit tester la carte réseau pour s’assurer que le matériel est correctement configuré. Si le pilote doit attendre que des modifications d’état se produisent dans le matériel, MiniportInitializeEx peut utiliser la fonction NdisWaitEvent ou la fonction NdisMSleep .

Une fois que MiniportInitializeEx est retourné avec succès, l’adaptateur miniport est dans l’état Suspendu . NDIS peut appeler la fonction MiniportRestart pour faire passer l’adaptateur miniport à l’état En cours d’exécution .

Si MiniportInitializeEx retourne NDIS_STATUS_SUCCESS, le pilote doit libérer toutes les ressources de l’adaptateur miniport dans la fonction MiniportHaltEx .

Le pilote doit appeler NdisMSetMiniportAttributes et définir generalAttributes dans la structure NDIS_MINIPORT_ADAPTER_ATTRIBUTES s’il retourne NDIS_STATUS_SUCCESS.

Si MiniportInitializeEx a échoué, MiniportInitializeEx doit libérer toutes les ressources qu’il a allouées avant de retourner et l’adaptateur miniport revient à l’état Arrêté .

NDIS appelle MiniportInitializeEx à IRQL = PASSIVE_LEVEL.

Exemples

Pour définir une fonction MiniportInitializeEx , 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 MiniportInitializeEx nommée « MyInitializeEx », utilisez le type MINIPORT_INITIALIZE comme indiqué dans cet exemple de code :

MINIPORT_INITIALIZE MyInitializeEx;

Ensuite, implémentez votre fonction comme suit :

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

Le type de fonction MINIPORT_INITIALIZE 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_INITIALIZE 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