Implémenter un rééquilibrage PnP pour les pilotes audio PortCls

Le rééquilibrage PnP est utilisé dans certains scénarios PCI où les ressources mémoire doivent être réallouées.

Le rééquilibrage peut être déclenché dans deux principaux scénarios :

1. Hotplug PCI : Un utilisateur branche un appareil et le bus PCI n’a pas suffisamment de ressources pour charger le pilote du nouvel appareil. Quelques exemples d’appareils qui entrent dans cette catégorie incluent Thunderbolt, USB-C et le stockage NVME. Dans ce scénario, les ressources mémoire doivent être réarrangées et consolidées (rééquilibrées) pour prendre en charge les appareils supplémentaires ajoutés.
2. BARs redimensionnables PCI : Après qu’un pilote pour un appareil est chargé en mémoire avec succès, il demande des ressources supplémentaires. Quelques exemples d’appareils incluent des cartes graphiques haut de gamme et des appareils de stockage. Pour plus d’informations sur la prise en charge des pilotes vidéo, veuillez consulter la section Prise en charge des BARs redimensionnables. Cette rubrique décrit ce qui doit être fait pour implémenter le rééquilibrage PnP pour les pilotes audio PortCls.

Le rééquilibrage PnP est disponible dans Windows 10, version 1511 et les versions ultérieures de Windows.

Exigences de rééquilibrage

Les pilotes audio PortCls ont la capacité de prendre en charge le rééquilibrage si les conditions suivantes sont remplies :

• Le miniport doit enregistrer l’interface IAdapterPnpManagement avec PortCls.
• Le miniport doit retourner PcRebalanceRemoveSubdevices à partir de IAdapterPnpManagement::GetSupportedRebalanceType.
• Les types de ports pris en charge sont Topology et WaveRT.

Pour prendre en charge le rééquilibrage lorsqu’il y a des flux audio actifs, les pilotes audio PortCls doivent répondre à l’une de ces deux exigences supplémentaires.

• Le pilote prend en charge les interfaces de paquets IMiniportWaveRTInputStream::GetReadPacket et IMiniportWaveRTOutputStream pour le flux audio. C'est l'option recommandée.

OR

• Si le pilote ne prend pas en charge get/write IMiniportWaveRT pour les flux, le pilote ne doit pas prendre en charge KSPROPERTY_RTAUDIO_POSITIONREGISTER et KSPROPERTY_RTAUDIO_CLOCKREGISTER. Dans ce scénario, le moteur audio utilisera IMiniportWaveRTStream::GetPosition.

Comportement du flux audio lors du rééquilibrage

Si le rééquilibrage est déclenché alors qu’il y a des flux audio actifs et que le pilote prend en charge le rééquilibrage pour les flux audio actifs, alors tous les flux audio actifs seront arrêtés et ils ne redémarreront pas automatiquement.

Interface COM IPortClsPnp

IPortClsPnp est l’interface de gestion PnP que le pilote de classe de port (PortCls) expose à l’adaptateur.

IPortClsPnp hérite de IUnknown et prend également en charge les méthodes suivantes :

• IPortClsPnp::RegisterAdapterPnpManagement
• IPortClsPnp::UnregisterAdapterPnpManagement

Les pilotes de miniport audio peuvent enregistrer une interface de notification PNP en utilisant les exports PortCls ou via l’interface COM IPortClsPnp exposée sur l’objet de port WaveRT. Utilisez IPortClsPnp::RegisterAdapterPnpManagement et IPortClsPnp::UnregisterAdapterPnpManagement pour inscrire et désinscrire.

DDIs d’exportation PortCls requis

IAdapterPnpManagement est une interface que les adaptateurs doivent implémenter et enregistrer s’ils veulent recevoir des messages de gestion PnP. Inscrivez cette interface avec PortCls en utilisant PcRegisterAdapterPnpManagement. Désinscrivez cette interface avec PortCls en utilisant PcUnregisterAdapterPnpManagement.

DDIs de pilote requis

Les DDIs IAdapterPnpManagement suivants doivent être implémentés pour prendre en charge le rééquilibrage.

• IAdapterPnpManagement::GetSupportedRebalanceType est appelé par PortCls lors du traitement de QueryStop. Le miniport retourne le type de rééquilibrage pris en charge tel que défini dans l’énumération PC_REBALANCE_TYPE.

  Remarque : PortCls acquiert le verrou global de l’appareil avant d’effectuer cet appel, donc le miniport doit exécuter cet appel aussi rapidement que possible.

• IAdapterPnpManagement::P npQueryStop est invoqué par PortCls juste avant de réussir l’IRP QueryStop. Ceci est juste une notification et l’appel ne retourne pas de valeur.

  Remarque : PortCls acquiert le verrou global de l’appareil avant d’effectuer cet appel, donc le miniport doit exécuter cet appel aussi rapidement que possible. Lorsqu’un arrêt est en attente, PortCls bloquera (maintient) toutes les nouvelles demandes de création.

• IAdapterPnpManagement::P npCancelStop est invoqué par PortCls lors du traitement de l’IRP CancelStop. Ceci est juste une notification. Il est possible pour le miniport de recevoir PnpCancelStop même sans avoir préalablement reçu une notification PnpQueryStop. Le miniport doit être écrit pour s’adapter à ce comportement. Par exemple, c’est le cas lorsque la logique QueryStop échoue l’IRP avant que PortCls n’ait l’opportunité de transmettre cette notification au miniport. Dans ce scénario, le gestionnaire PnP invoque toujours un arrêt d’annulation PnP.

  Remarque : PortCls acquiert le verrou global de l’appareil avant d’effectuer cet appel, donc le miniport doit exécuter cet appel aussi rapidement que possible. Lorsqu’un arrêt est en attente, PortCls bloquera (maintient) toutes les nouvelles demandes de création. PortCls redémarre toutes les demandes de création en attente lorsqu’un arrêt en attente est annulé.

• IAdapterPnpManagement::PnpStop est invoqué par PortCls après avoir arrêté toutes les opérations Ioctl et déplacé les flux actifs de l’état [run|pause|acquire] à l’état [stop]. Cet appel n’est pas effectué en tenant le verrou global de l’appareil. Ainsi, le miniport a l’opportunité d’attendre ses opérations asynchrones (éléments de travail, dpc, threads asynchrones) et de désinscrire ses sous-périphériques audio. Avant de retourner de cet appel, le miniport doit s’assurer que toutes les ressources matérielles ont été libérées.

  Remarque : Le miniport ne doit pas attendre que les objets miniport/flux actuels soient supprimés puisqu’il est incertain quand les clients audio existants libéreront les poignées actuelles. Le thread PnpStop ne peut pas bloquer indéfiniment sans planter le système, c’est-à-dire, c’est un thread PnP/Power.

IMiniportPnpNotify

IMiniportPnpNotify est une interface optionnelle permettant aux objets miniport (sous-périphériques audio) de recevoir des notifications de changement d’état PnP.

Les miniports ont l’opportunité de recevoir une notification d’arrêt PnP pour chaque sous-périphérique audio qu’ils ont enregistré. Pour recevoir cette notification, le sous-périphérique doit prendre en charge IMiniportPnpNotify. Seule la notification IMiniportPnpNotify::PnpStop est définie sur cette interface.

L’interface IMiniportPnpNotify est disponible à la fois sur WaveRT et Topology.

Remarque : Comme PortCls acquiert le verrou global de l’appareil avant d’effectuer cet appel, le miniport doit exécuter cet appel aussi rapidement que possible. Le miniport ne doit pas attendre d’autres activités pendant le traitement de cet appel pour éviter un blocage lorsque d’autres threads/éléments de travail attendent le verrou global de l’appareil. Si nécessaire, le miniport peut attendre dans l’appel IAdapterPnpManagement::PnpStop.