Interfaces du pilote IHV WDI

Le miniport WDI IHV est comme n’importe quel autre pilote miniport NDIS et il suivrait les pratiques de développement et la documentation pour n’importe quel miniport NDIS. Les responsabilités d’un pilote Miniport WLAN natif pour les gestionnaires NDIS sont réparties entre le composant MS et le pilote WDI IHV. Le composant WLAN microsoft prend en charge les exigences NDIS applicables à tous les miniports Wi-Fi afin que chaque IHV n’ait pas à refaire tout ce travail. Le mappage et les changements de comportement pour les gestionnaires NDIS pour le miniport IHV WLAN natif lorsqu’ils sont appliqués à un miniport WDI IHV sont décrits ci-dessous.

• Installation du pilote
• DriverEntry
• MiniportSetOptions
• MiniportInitializeEx
• MiniportHaltEx
• MiniportDriverUnload
• MiniportPause
• MiniportRestart
• MiniportResetEx
• MiniportDevicePnPEventNotify
• MiniportShutdownEx
• MiniportOidRequest
• MiniportCancelOidRequest
• NdisMIndicateStatusEx
• MiniportDirectOidRequest
• MiniportCancelDirectOidRequest
• MiniportSendNetBufferLists
• MiniportCancelSend
• MiniportReturnNetBufferLists
• Gestionnaire WDI : MiniportWdiOpenAdapter
• Gestionnaire WDI : MiniportWdiCloseAdapter

Installation du pilote

Aucune modification n’est apportée à la façon dont le pilote miniport WDI IHV est chargé et installé sur le système. Le processus INF et d’installation est similaire à celui d’un pilote miniport IHV Native WLAN. Comme les pilotes NDIS existants, lorsque le pilote IHV doit être chargé pour fonctionner avec l’adaptateur WLAN de l’IHV, le système d’exploitation appelle la routine DriverEntry du pilote IHV miniport.

DriverEntry

Le système d’exploitation appelle directement la routine DriverEntry du pilote WDI IHV miniport. Le miniport IHV suit la plupart des directives d’un miniport NDIS normal routine DriverEntry. La seule exception est qu’au lieu d’appeler NdisMRegisterMiniportDriver, le miniport IHV appelle NdisMRegisterWdiMiniportDriver pour indiquer au système d’exploitation d’activer le composant Microsoft WLAN.

Voici les paramètres clés de NdisMRegisterWdiMiniportDriver.

• NDIS_MINIPORT_DRIVER_CHARACTERISTICS : il s’agit de la structure NDIS d’origine qu’un miniport natif Wi-Fi utilise pour s’inscrire auprès de NDIS. Pour un modèle WDI, la plupart des paramètres de gestionnaire sont facultatifs. Les seuls gestionnaires requis sont MINIPORT_OID_REQUEST_HANDLER et MINIPORT_DRIVER_UNLOAD. MINIPORT_OID_REQUEST_HANDLER est utilisé pour transmettre des messages WDI au pilote IHV. Si un autre gestionnaire est spécifié, le composant MICROSOFT WLAN appelle généralement le gestionnaire après avoir effectué son propre traitement pour le gestionnaire.
• NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS : il s’agit du nouvel ensemble de gestionnaires qu’un pilote de miniport WDI doit implémenter. Il est utilisé par le pilote IHV pour inscrire des gestionnaires supplémentaires pour le chemin du contrôle et l’ensemble complet de gestionnaires pour le chemin des données.

Lorsque le miniport IHV appelle NdisMRegisterWdiMiniportDriver, le composant Microsoft WLAN met à jour les gestionnaires de NDIS_MINIPORT_DRIVER_CHARACTERISTICS et appelle le NdisMRegisterMiniportDriver de NDIS. Les mises à jour sont effectuées afin que le composant Microsoft WLAN puisse intercepter les gestionnaires pour lesquels il peut fournir une assistance/simplification au pilote miniport WDI IHV.

Voici le flux standard du processus DriverEntry pour le pilote WDI IHV miniport

Pour plus d’informations sur DriverEntry, consultez DriverEntry of NDIS Miniport Drivers.

MiniportSetOptions

Comme indiqué dans le diagramme DriverEntry ci-dessus, si le miniport WDI IHV a inscrit le gestionnaire MiniportSetOptions , le système d’exploitation appelle cette fonction dans le contexte du pilote miniport appelant NdisMRegisterWdiMiniportDriver.

Si le pilote de miniport IHV inscrit des gestionnaires d’options à l’aide de NdisSetOptionalHandlers, ces gestionnaires peuvent ne pas être sérialisés via la couche WDI par le composant Microsoft. Par conséquent, le composant IHV est responsable de la gestion des exigences de synchronisation pour ces gestionnaires.

MiniportInitializeEx

Le modèle WDI fractionne le comportement MiniportInitializeEx en plusieurs appels d’interface WDI.

1. Appelez MiniportWdiAllocateAdapter.

   Lorsque le système d’exploitation trouve une instance du matériel IHV, il s’agit du premier appel au pilote miniport WDI IHV. Dans cet appel, le miniport WDI effectue les actions requises pour créer une représentation logicielle (MiniportAdapterContext) de l’appareil. Il détermine également les informations sur l’appareil à remplir dans la structure NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES . L’initialisation réelle de l’appareil et de la pile Wi-Fi est effectuée ultérieurement lorsque le composant Microsoft envoie des commandes WDI vers le bas pour effectuer des initialisations spécifiques.

   À l’aide des données obtenues à partir du pilote miniport WDI IHV, le composant Microsoft appelle NdisMSetMiniportAttributes et définit le NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES sur NDIS. La plupart des champs de NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES sont remplis avec les valeurs par défaut par le composant Microsoft. Le pilote IHV doit remplir les champs MiniportAdapterContext et InterfaceType .

   Une fois cet appel retourné par le pilote IHV miniport, il commence à recevoir des commandes WDI via son gestionnaire MiniportOidRequest . Pendant cet appel, le composant Microsoft peut ne pas être en mesure d’effectuer des opérations de réinitialisation/récupération. Par conséquent, toute activité effectuée ici doit être rapide et fiable.

2. Appelez MiniportWdiOpenAdapter.

   Après MiniportWdiAllocateAdapter, le composant Microsoft appelle MiniportWdiOpenAdapter pour charger le microprogramme et initialiser le matériel.

3. Plusieurs commandes WDI à l’aide de MiniportOidRequest.

   Après MiniportWdiOpenAdapter, le composant Microsoft envoie les tâches/propriétés/appels suivants au miniport IHV.

   1. Appelez MiniportWdiTalTxRxInitialize pour initialiser le chemin des données et les gestionnaires d’échange.
   2. Appelez OID_WDI_GET_ADAPTER_CAPABILITIES pour obtenir les fonctionnalités de l’adaptateur.
   3. Appelez OID_WDI_SET_ADAPTER_CONFIGURATION pour configurer l’adaptateur.
   4. Appelez OID_WDI_TASK_SET_RADIO_STATE pour définir l’état radio initial s’il n’est pas déjà dans l’état attendu.
   5. Appelez MiniportWdiTalTxRxStart pour configurer le chemin des données.
   6. Appelez OID_WDI_TASK_CREATE_PORT pour créer le port initial.

   D’autres commandes peuvent également être envoyées au composant IHV dans le cadre du traitement MiniportInitializeEx du composant Microsoft. Toutefois, tant que MiniportWdiStartOperation n’est pas appelé, le composant Microsoft n’envoie aucune tâche vers le bas qui nécessite une communication otaie. À l’exception des OID_WDI_TASK_OPEN toujours envoyées en premier, l’ordre des autres commandes/appels peut changer.

   À l’aide des données obtenues à partir du pilote miniport WDI IHV, le composant Microsoft appelle NdisMSetMiniportAttributes et définit NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES et NDIS_MINIPORT_ADAPTER_NATIVE_802_11_ATTRIBUTES sur NDIS.

4. Appelez MiniportWdiStartOperation.

   Il s’agit d’un gestionnaire de miniport WDI facultatif dans NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS que le pilote IHV peut utiliser pour effectuer des tâches MiniportInitializeEx supplémentaires. Il peut également être utilisé par le miniport IHV pour indiquer que le composant Microsoft a terminé d’initialiser le miniport et que le miniport peut démarrer toutes les activités d’arrière-plan nécessaires.

   Le diagramme ci-dessous montre le flux de MiniportInitializeEx.

   

   Si une opération intermédiaire échoue, le composant Microsoft annule les opérations précédentes et échoue à l’affichage du miniport. Par exemple, si OID_WDI_TASK_CREATE_PORT échoue, le chemin des données est nettoyé, OID_WDI_TASK_CLOSE est envoyé et le miniport échoue.

MiniportHaltEx

Dans un miniport native Wi-Fi, MiniportHaltEx est utilisé pour indiquer au miniport d’arrêter les opérations et de propre l’adaptateur instance. Dans le modèle WDI, le composant Microsoft gère l’appel MiniportHaltEx d’origine et le fractionne en plusieurs appels d’interface WDI.

1. Appelez MiniportWdiStopOperation.

   Il s’agit d’un gestionnaire de miniport WDI facultatif dans NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS que le pilote IHV peut utiliser pour annuler les opérations qu’il a effectuées dans MiniportWdiStartOperation.

2. Plusieurs commandes WDI à l’aide de MiniportOidRequest.

   Après MiniportWdiStopOperation, le composant Microsoft envoie des tâches/propriétés au miniport IHV pour propre l’état actuel du pilote IHV. Ce nettoyage peut inclure les éléments suivants.

   1. Appelez OID_WDI_TASK_DISCONNECT/OID_WDI_TASK_STOP_AP pour supprimer toutes les connexions existantes.
   2. Appelez OID_WDI_TASK_DELETE_PORT pour supprimer tous les ports créés.
   3. Appelez MiniportWdiTalTxRxStop pour arrêter le chemin des données.
   4. Appelez MiniportWdiTalTxRxDeinitialize pour désinitialiser le chemin des données.
   5. Appelez pour propre l’état du matériel. Celui-ci est envoyé à l’IHV à l’aide du MiniportWdiCloseAdapter qui a été enregistré par le pilote IHV.

3. Une fois toutes les commandes ci-dessus appelées, le composant Microsoft appelle MiniportWdiFreeAdapter pour que le pilote IHV supprime tout état logiciel qu’il peut avoir.

Le diagramme ci-dessous montre le flux de MiniportHaltEx.

Le traitement MiniportHaltEx n’est pas effectué si l’appareil est supprimé par surprise ou si le système est hors tension. Pour une suppression surprise, reportez-vous au comportement du gestionnaire MiniportDevicePnPEventNotify . Pour l’arrêt du système, reportez-vous au comportement du gestionnaire MiniportShutdownEx .

MiniportDriverUnload

MiniportDriverUnload est le gestionnaire appelé avant le déchargement du miniport WDI IHV. Le pilote WDI IHV miniport appelle le composant Microsoft pour se désinscrire. Le composant Microsoft appelle NdisMDeregisterMiniportDriver.

Le diagramme ci-dessous montre le flux de MiniportDriverUnload.

MiniportPause

Les exigences de NDIS MiniportPause sont gérées par le composant Microsoft. Dans le cadre de MiniportPause, le composant Microsoft arrête le chemin des données et attend qu’elles propre. Le miniport WDI IHV peut éventuellement s’inscrire à un rappel MiniportWdiPostAdapterPause appelé par le composant Microsoft une fois le nettoyage du chemin de données terminé.

Le diagramme ci-dessous montre le flux de MiniportPause.

MiniportRestart

Les exigences de miniportRestart de NDIS sont gérées par le composant Microsoft. Dans le cadre de MiniportRestart, le composant Microsoft annule le travail de pause du chemin de données qu’il a effectué dans le cadre de MiniportPause. Le miniport WDI IHV peut éventuellement s’inscrire à un rappel MiniportWdiPostAdapterRestart appelé par le composant Microsoft une fois qu’il a terminé le redémarrage du chemin des données.

Le diagramme ci-dessous montre le flux de MiniportRestart.

MiniportResetEx

MiniportResetEx n’est pas géré par le composant Microsoft. Le miniport WDI IHV peut éventuellement s’inscrire à un rappel MiniportResetEx appelé par le composant Microsoft.

MiniportDevicePnPEventNotify

MiniportDevicePnPEventNotify est utilisé pour notifier un pilote NDIS d’événements PNP tels que la suppression surprise d’un appareil. Lorsque NDIS envoie cette notification, elle est d’abord transférée au miniport WDI IHV pour traitement. Une fois que le composant IHV a terminé son traitement, le composant Microsoft effectue le traitement approprié pour cet événement. L’appel transféré vers le composant IHV n’est pas sérialisé avec d’autres tâches et rappels.

Le diagramme ci-dessous montre le flux de MiniportDevicePnPEventNotify.

MiniportShutdownEx

MiniportShutdownEx est utilisé pour informer un pilote NDIS des événements d’arrêt du système. Lorsque NDIS envoie cette notification, elle est d’abord gérée par le composant Microsoft. Une fois que le composant Microsoft a terminé de le traiter, il transmet l’événement au miniport WDI IHV pour traitement.

Le diagramme ci-dessous montre le flux de MiniportShutdownEx.

MiniportOidRequest

Le gestionnaire MiniportOidRequest est un gestionnaire obligatoire que le miniport WDI IHV doit implémenter. Il est utilisé par le composant Microsoft pour envoyer des commandes WDI au miniport IHV. Il est également utilisé pour transférer des OID que le composant Microsoft ne gère pas vers le miniport IHV.

L’appel MiniportOidRequest dans le miniport WDI IHV doit être considéré comme le message M1 d’une commande WDI. L’achèvement de l’OID (via NdisMOidRequestComplete ou via un retour non-PENDING à partir de MiniportOidRequest) doit être considéré comme le message M3 pour une tâche/commande WDI.

Pour chaque commande WDI, il existe deux champs potentiels dans lesquels un code NDIS_STATUS peut être retourné pour l’opération : le code status de l’appel MiniportOidRequest (ou NdisMOidRequestComplete) et le code status dans le champ WDI_MESSAGE_HEADER (soit sur l’achèvement OID, soit via NdisMIndicateStatusEx). Le composant Microsoft examine toujours le NDIS_STATUS de la saisie semi-automatique OID avant d’examiner le champ WDI_MESSAGE_HEADERStatus . Les attentes du composant IHV pour le traitement OID WDI sont les suivantes.

1. Les OID WDI sont envoyés au composant IHV à l’aide d’un NDIS_OID_REQUESTRequestType de NdisRequestMethod, et la longueur du message et la longueur du message correspondantes se trouvent dans les DONNÉES. METHOD_INFORMATION. InformationBuffer et DATA. METHOD_INFORMATION. Champs InputBufferLength respectivement.
2. Le composant IHV signale une erreur dans l’exécution de l’OID en cas d’erreur lors du traitement de la commande, et définit le champ État du WDI_MESSAGE_HEADER sur non-réussite s’il présente une défaillance de niveau Wi-Fi.
3. Pour les tâches et les propriétés, le numéro de port de la demande se trouve dans le champ PortId WDI_MESSAGE_HEADER. PortNumber dans le NDIS_OID_REQUEST est toujours défini sur 0.
4. Pour l’achèvement de l’OID, il est acceptable que miniportOidRequest retourne NDIS_STATUS_PENDING et termine l’OID ultérieurement (de manière synchrone ou asynchrone) avec NdisMOidRequestComplete.
5. Si le composant IHV termine l’OID avec NDIS_STATUS_SUCCESS, il doit remplir le champ BytesWritten de la requête OID avec le nombre approprié d’octets, y compris l’espace pour le WDI_MESSAGE_HEADER.
6. Si le composant IHV n’a pas suffisamment d’espace dans les données. METHOD_INFORMATION. Champ OutputBufferLength pour remplir la réponse, il complète l’OID avec NDIS_STATUS_BUFFER_TOO_SHORT et remplit les DONNÉES. METHOD_INFORMATION. Champ BytesNeeded. Le composant Microsoft peut tenter d’allouer une mémoire tampon de la taille demandée et de soumettre une nouvelle demande à l’IHV.
7. S’il s’agit d’une tâche, le M4 (NdisMIndicateStatusEx) de la tâche ne doit être indiqué que si la tâche a été signalée comme démarrée avec succès. L’exécution de l’OID a réussi et l’état dans le WDI_MESSAGE_HEADER dans l’achèvement OID a réussi.

Le diagramme ci-dessous montre un exemple de requête OID NDIS qui correspond à une seule commande WDI. Lorsque la demande OID est envoyée par le système d’exploitation, le composant Microsoft la convertit en requête OID WDI et envoie la demande OID WDI au miniport IHV. Lorsque le miniport IHV termine l’OID, le composant Microsoft effectue correctement la requête OID d’origine.

Si OriginalOidRequest est mappé à plusieurs OidRequests WDI et qu’une des requêtes WDI échoue, l’OriginalOidRequest échoue également. Si un sous-ensemble des opérations intermédiaires est déjà terminé, le composant Microsoft tente d’annuler les opérations qui prennent en charge propre.

Le diagramme ci-dessous montre un exemple de requête OID NDIS gérée par le composant Microsoft. Lorsque la demande OID est envoyée par le système d’exploitation, le composant Microsoft traite et termine l’OID. Cet OID n’est pas passé au miniport WDI IHV.

Les OID qui ne sont pas compris par le composant Microsoft sont transférés directement au composant IHV pour traitement.

Le comportement de MiniportOidRequest est inchangé pour le pilote WDI IHV miniport (par rapport à un miniport Native Wi-Fi). Les appels sont sérialisés et le miniport IHV peut le terminer de manière synchrone ou asynchrone avec un appel à NdisMOidRequestComplete.

MiniportCancelOidRequest

Il s’agit d’un gestionnaire facultatif utilisé par un miniport WDI IHV qui doit gérer les OID qui ne sont pas mappés aux messages WDI. Ce gestionnaire n’est pas utilisé pour les OID WDI. Les OID WDI doivent se terminer rapidement et il n’est pas nécessaire que le pilote miniport IHV tente d’annuler un OID en attente. L’annulation des tâches WDI est gérée à l’aide de la demande OID de tâche d’annulation appropriée. Pour les OID non mappés, le comportement attendu est défini par NDIS.

NdisMIndicateStatusEx

NdisMIndicateStatusEx est utilisé par le miniport WDI IHV pour envoyer des indications au composant Microsoft. Il peut s’agir d’indications non sollicitées telles que des défaillances du MIC TKIP ou d’indications demandées pour l’achèvement (M4) d’une tâche.

Le diagramme ci-dessous montre un exemple d’indication WDI qui a une indication NDIS/Native Wi-Fi correspondante. Lorsque l’indication est envoyée par le miniport IHV au composant Microsoft, le composant Microsoft la convertit en une indication existante et la transfère au système d’exploitation.

Le diagramme ci-dessous montre un exemple d’indication WDI qui n’a aucune indication NDIS/Native Wi-Fi correspondante. Cela est géré par le composant Microsoft.

Le diagramme ci-dessous montre une indication qui n’est pas reconnue par le composant Microsoft. L’indication est transférée en l’état au système d’exploitation.

Le comportement de NdisMIndicateStatusEx est inchangé pour le pilote WDI IHV miniport (par rapport à un miniport Native Wi-Fi).

MiniportDirectOidRequest

Il s’agit d’un gestionnaire facultatif inscrit par un pilote miniport IHV WDI s’il doit gérer les OID directs qui ne sont pas mappés aux messages WDI. Tous les OID direct existants pour Wi-Fi Direct sont mappés aux messages WDI. Ce gestionnaire n’est donc pas nécessaire pour prendre en charge cette fonctionnalité. Les OID direct non pris en charge ne sont pas sérialisés par le composant Microsoft.

MiniportCancelDirectOidRequest

Il s’agit d’un gestionnaire facultatif utilisé par un miniport WDI IHV qui doit gérer les OID directs qui ne sont pas mappés aux messages WDI. Pour les OID non mappés, le comportement attendu est défini par NDIS.

MiniportSendNetBufferLists

Ce gestionnaire n’est pas utilisé dans un pilote miniport WDI IHV et ne doit pas être fourni. Le composant Microsoft utilise les gestionnaires de chemins de données inscrits via NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS pour envoyer des paquets d’envoi au miniport IHV.

MiniportCancelSend

Ce gestionnaire n’est pas utilisé dans un pilote miniport WDI IHV et ne doit pas être fourni.

MiniportReturnNetBufferLists

Ce gestionnaire n’est pas utilisé dans un pilote WDI IHV Miniport et ne doit pas être fourni. Le composant Microsoft utilise les gestionnaires de chemins de données inscrits via NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS pour retourner les paquets reçus au miniport IHV.

Gestionnaire WDI : MiniportWdiOpenAdapter

Le gestionnaire MiniportWdiOpenAdapter est utilisé par le composant Microsoft pour lancer l’opération Ouvrir la tâche sur le pilote IHV. Cet appel doit se terminer rapidement et si l’opération d’ouverture a démarré avec succès, l’IHV doit retourner NDIS_STATUS_SUCCESS sur cet appel et appeler le gestionnaire OpenAdapterComplete qui est passé dans le paramètre NDIS_WDI_INIT_PARAMETERS de MiniportWdiAllocateAdapter.

Gestionnaire WDI : MiniportWdiCloseAdapter

Le gestionnaire MiniportWdiCloseAdapter est utilisé par le composant Microsoft pour lancer l’opération Fermer la tâche sur le pilote IHV. Cet appel doit se terminer rapidement et si l’opération d’ouverture a été correctement démarrée, l’IHV doit retourner NDIS_STATUS_SUCCESS sur cet appel et appeler le gestionnaire CloseAdapterComplete qui est passé dans le paramètre NDIS_WDI_INIT_PARAMETERS du MiniportWdiAllocateAdapter.