Énumération d’appareils ACX

Article
01/30/2025

Cette rubrique traite de l’énumération d’appareils ACX, du démarrage et de l’arrêt, et du rééquilibrage de l’appareil. Pour obtenir une vue d’ensemble générale d’ACX, consultez vue d’ensemble des extensions de classe audio ACX. Pour plus d'informations sur la gestion de l'alimentation ACX et PnP, voir gestion de l'alimentation ACX.

Énumération et démarrage de l’appareil ACX pour les appareils audio statiques

Pour en savoir plus sur le fonctionnement du démarrage d’ACX, le scénario suivant sera décrit.

Un périphérique audio est représenté par un circuit unique.
Une durée de vie audio/circuit est liée à la durée de vie de l’appareil PnP.
Un seul appareil peut créer plusieurs circuits pour différents appareils audio.
Environnement KMDF en mode noyau.

La séquence de démarrage est la suivante :

WDM DriverEntry. Portée du pilote. DriverEntry pour la routine des pilotes WDF.
- Init tracing.
- Enregistrement facultatif pour le déchargement.
- Créez WDFDRIVER.
- Appelez ACX pour effectuer toute opération d'initialisation postérieure à la création du pilote.
- Optionnellement, effectuez une post-initialisation du pilote.
WDF DeviceAdd. À l'échelle de l'appareil. Fonction de rappel EVT_WDF_DRIVER_DEVICE_ADD
- Appeler ACX pour initialiser le contexte d'initialisation de l’appareil - ACX_DEVICEINIT_CONFIG_INIT(&devInitCfg)fonction ACX_DEVICEINIT_CONFIG_INIT
- Enregistrer les fonctions de rappel de l'alimentation PnP de la WDF - WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&pnpPowerCallbacks);
- Créer un appareil à l’aide de AcxDeviceInitialize
- Appelez l'ACX pour effectuer toute opération de post-initialisation de l'appareil.
- Optionnellement, effectuez n'importe quelle initialisation après l'appareil.
WDF PrepareHardware. À l'échelle de l'appareil. Fonction de rappel EVT_WDF_DEVICE_PREPARE_HARDWARE.
- Créez et initialisez des ressources matérielles (pour les interruptions et les threads, inscrivez-les auprès d’ACX).
- Créez un ou plusieurs circuits (création ponctuelle).
  - Créez un contexte AcxCircuitInit.
  - Ajoutez des rappels.
  - Créez un AcxCircuit.
  - Effectuez éventuellement un init post-circuit.
  - Enregistrez le circuit avec AcxDeviceAddCircuitDevice.
Rappel d'entrée de l'appareil WDF D0. À l'échelle de l'appareil. Fonction de rappel EVT_WDF_DEVICE_D0_ENTRY.
ACX invoque la fonction de rappel EvtAcxCircuitPowerUp sur tous les circuits. Circuit-scoped.
ACX déplace les flux (le cas échéant) vers leur état précédent avant que l’appareil ne soit mis hors tension. Étendue de l'instance de flux.
Les files d’attente WDF sont redémarrées.
Fonction de rappel EVT_WDF_DEVICE_SELF_MANAGED_IO_INIT. À l'échelle de l'appareil.
EVT_WDF_DEVICE_SELF_MANAGED_IO_RESTART callback function. À l'échelle de l'appareil. - Init après chaque mise sous tension à partir de Dx.

Ajout de flux ACX

Ajout de flux ACX (instance) sur circuit ACX (rappel ACX sur circuits ACX) - invoqué à tout moment après que la fonction WDF Self-managed I/O Init ou Restart a été invoquée et que l'appareil est en D0. Circuit-scoped.
- Entrée : Contexte AcxStreamInit, ACXCIRCUIT.
- Ajoutez des rappels.
- Créez un AcxStream (instance).
- Il est possible d'effectuer un init de l'instance après la création du flux.
- En retour, l'ACX active cette instance de flux, et puisque dans ce scénario c'est la seule sur le chemin audio, elle permet aux messages de flux de passer.

Énumération et démarrage des appareils ACX pour les appareils audio dynamiques

Dans ce scénario, les éléments suivants sont supposés.

Prise en charge audio dynamique (créer/supprimer des appareils audio au moment de l’exécution).
La durée de vie de l’appareil n’est pas liée à la durée de vie du circuit.
Un seul appareil peut créer plusieurs circuits pour différents appareils audio.
S'appuie sur le modèle statique simple décrit ci-dessus en ajoutant uniquement des éléments spécifiques au schéma dynamique.
Utilise les PDO bruts de l'enfant.
Environnement KMDF en mode noyau.

La séquence de démarrage pour ce scénario est la suivante :

WDM DriverEntry. Portée du pilote.
- Init tracing.
- Enregistrement facultatif pour le déchargement.
- Créez WDFDRIVER.
- Appelez ACX pour effectuer toute opération d'initialisation postérieure à la création du pilote.
- Optionnellement, effectuez une post-initialisation du pilote.
WDF DeviceAdd. À l'échelle de l'appareil.
- Appelez ACX pour initialiser le contexte d'initialisation de l'appareil.
- Créez un appareil.
- Appelez ACX pour effectuer toute initialisation post-appareil.
- Optionnellement, effectuez n'importe quelle initialisation après l'appareil.
WDF PrepareHardware. À l'échelle de l'appareil.
- Créez et initialisez des ressources matérielles (pour les interruptions et les threads, inscrivez-les auprès d’ACX).
Rappel d'entrée de l'appareil WDF D0. À l'échelle de l'appareil.
Les files d’attente WDF sont redémarrées.
WDF DeviceSelfManagedIoInit. À l'échelle de l'appareil.
WDF DeviceSelfManagedIoRestart. À l'échelle de l'appareil.
- Init après chaque mise sous tension à partir de Dx.

Création dynamique du circuit (à tout moment)

Le pilote alloue une structure WDFDEVICE_INIT en appelant WdfPdoInitAllocate. Le pilote est responsable de l'appel à WdfDeviceInitFree s'il rencontre des échecs avant la création réussie d'un appareil.
Le pilote spécifie les rappels PnP/alimentation qu’il souhaite recevoir.
Le pilote crée un appareil.
Le pilote instancie le nouvel appareil/circuit en appelant AcxDeviceAddCircuitDevice.
WDF/PnP prend le relais et le modèle simple d'enums/démarrage décrit dans la section précédente se met en place.

AcxFactoryCircuit

Un pilote ACX peut également créer des objets AcxFactoryCircuit (fournisseurs de circuits) pendant la séquence d’alimentation à l’aide de la fonction AcxFactoryCircuitCreate et de la fonction AcxDeviceAddFactoryCircuit.

Étant donné que le pilote ACX s'est enregistré auprès de l'ACX en tant que fabrique de circuits, le cadre ACX utilise la fabrique enregistrée pour demander au pilote de créer un nouveau circuit.

AcxFactoryCircuitCreate(Device, &attributes, &factoryInit, &factory);

AcxDeviceAddFactoryCircuit(Device, factory);

Rééquilibrage de l’appareil ACX

Le rééquilibrage est effectué lorsque l’utilisation des ressources système nécessite que le système d’exploitation rééquilibrer les ressources entre les appareils. Pour obtenir des informations générales sur le rééquilibrage, consultez Implémenter le rééquilibrage PnP pour les pilotes audio PortCls.

ACX prend en charge le rééquilibrage des appareils comme suit :

Dans la séquence WDF/ACX de mise hors tension, le pilote libère toutes les ressources de streaming (EvtAcxStreamPowerDown, EvtAcxStreamReleaseHardware), les ressources de circuit (EvtAcxCircuitPowerDown, EvtAcxCircuitReleaseHardware) et les ressources de périphérique (EvtDeviceReleaseHardware).
Toutes les requêtes sont suspendues et les handles restent ouverts.
Dans la séquence WDF/ACX de mise sous tension, le pilote s’assure que les nouvelles ressources sont compatibles avec les ressources actuelles et effectue les ajustements autorisés à ses paramètres. Si les ressources ne sont pas compatibles avec l’initialisation actuelle de l’appareil/du circuit, le pilote doit supprimer les circuits actuels et en créer de nouveaux. Voir ci-dessous plus d’informations.
Dans la séquence de mise sous tension, WDF invoque ses entrées EvtDevicePrepareHardware et EvtDeviceD0, et ACX invoque les entrées EvtAcxCircuitPrepareHardware et EvtAcxCircuitPowerUp correspondantes, et déplace tous les flux dans leurs états préexistants.
Dès que les files d'attente passent à l'état de mise sous tension/exploitation, le flux d'E/S reprend.

ACX n'autorise pas la suppression (échec query-remove) ou le rééquilibrage (échec query-stop) s'il y a des flux dans l'état actif (RUN).

Les pilotes peuvent également opter pour toujours détruire et recréer des périphériques audio lors du rééquilibrage. Il s’agit du même scénario ci-dessus lorsque l’appareil détecte que les nouveaux paramètres ne sont pas compatibles avec les anciens. La suppression du circuit doit être effectuée dans les rappels EvtDevicePrepareHardware/EvtDeviceReleaseHardware, et le nouveau circuit est recréé dans EvtDevicePrepareHardware. Le pilote supprime un circuit en désenregistrant le circuit (à l'aide de AcxDeviceRemoveCircuit). Les circuits d’usine ne doivent normalement pas être supprimés pendant le rééquilibrage.

Manipulations de fichiers en mode utilisateur

ACX n'attend pas que les handles de fichiers en mode utilisateur soient fermés avant de recréer de nouveaux circuits. La durée de vie des handles du système de fichiers n'est pas liée à la durée de vie des ressources matérielles utilisées par les appareils/circuits. Il incombe aux clients d'écouter l'arrivée/le retrait de l'interface et de fermer et rouvrir les poignées de fichiers.

Les anciens descripteurs de fichiers sont marqués comme obsolètes et ACX élimine toutes les requêtes d’E/S associées.