MINIPORT_INITIALIZE fonction de rappel (ndis.h)

Article
02/07/2025

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

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

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 gère 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 de retour

MiniportInitializeEx pouvez retourner l’une des valeurs d’état suivantes :

Retourner le code	Description
NDIS_STATUS_SUCCESS	MiniportInitializeEx configuré et configuré la carte miniport et alloué toutes les ressources que le pilote doit avoir pour effectuer des opérations d’E/S réseau.
NDIS_STATUS_NOT_ACCEPTED	MiniportInitializeEx n’a pas pu obtenir l’adaptateur miniport pour accepter les paramètres de configuration MiniportInitializeEx 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 fournit aux utilisateurs ou aux administrateurs système des informations qui peuvent être utilisées pour reconfigurer l’ordinateur afin d’éviter ces 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 retour du DriverEntry. Pour plus d’informations, consultez DriverEntry de NDIS Miniport Drivers.

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

Les pilotes peuvent s’inscrire en tant que pilote miniport combiné et pilote intermédiaire (voir NdisMRegisterMiniportDriver). Ce type de pilote miniport intermédiaire fonctionne de la même façon qu’un pilote intermédiaire superposé sur un pilote miniport physique. Pour chaque instance de périphérique virtuel ou physique 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. Dans le cas contraire, NDIS appelle la fonction MiniportInitializeEx du pilote inscrit pour l’appareil physique.

Jusqu’à MiniportInitializeEx retourne, NDIS n’envoie aucune demande d’initialisation de l’adaptateur miniport. L’adaptateur miniport est à l’état initialiser.

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 fournissez un NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES structure qui contient les attributs suivants :

Handle vers 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 d’interface.

Le pilote miniport passe NdisMSetMiniportAttributes un handle au MiniportAdapterContext membre de NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES. Le pilote conserve les informations d’état de 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 d’autres attributs.

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

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

Si le pilote indique qu’il reçoit avec le fonction NdisMIndicateReceiveNetBufferLists, la fonction MiniportInitializeEx doit appeler la fonction 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 structures de référence 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 doivent 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 pouvez appeler la fonction NdisAllocateTimerObject avec une fonction NetTimerCall back fournie par le pilote et un pointeur vers la mémoire allouée par le pilote pour un objet minuteur. Les pilotes peuvent configurer plusieurs fonctions NetTimerCallback, chacune avec son propre objet 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 unique.

MiniportInitializeEx doit appeler le fonction NdisMSetMiniportAttributes avant d’appeler une fonction NdisMXxx, telle que la fonction NdisMRegisterIoPortRange ou fonctions NdisMMapIoSpace, qui prétend des ressources matérielles pour l’adaptateur miniport. MiniportInitializeEx doit appeler NdisMSetMiniportAttributes avant de tenter d’allouer des ressources pour les opérations DMA.

Si l’appareil prend en charge la DMA maître de 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 MiniportInitializeEx appelle le fonction NdisMRegisterInterruptEx, NDIS peut appeler la fonction MiniportInterrupt du pilote. NDIS appelle MiniportInterrupt si la carte réseau génère une interruption ou si un 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 au fonction NdisMDeregisterInterruptEx retourne.

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

Après MiniportInitializeEx retourne correctement, l’adaptateur miniport est à l’état suspendu. NDIS peut appeler la fonction MiniportRestart pour passer de 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 la GeneralAttributes dans la structure NDIS_MINIPORT_ADAPTER_ATTRIBUTES si elle retourne NDIS_STATUS_SUCCESS.

Si MiniportInitializeEx a échoué, MiniportInitializeEx doit libérer toutes les ressources qu’elle a allouées avant son retour et l’adaptateur miniport revient à l’état arrêté.

NDIS appelle MiniportInitializeEx à IRQL = PASSIVE_LEVEL.

exemples de

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 fonctions permet d'Analyse du code pour les pilotes, de vérificateur de pilotes statiques (SDV) et d’autres outils de vérification recherchent des erreurs, et il est nécessaire d’écrire des 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 lorsque vous exécutez les 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 annoter le comportement de la fonction.

Exigences

Exigence	Valeur
client minimum pris en charge	Prise en charge dans NDIS 6.0 et versions ultérieures.
plateforme cible	Windows
d’en-tête	ndis.h (include Ndis.h)
IRQL	PASSIVE_LEVEL