Circuits ACX

Article
03/08/2024

Cette rubrique traite des circuits ACX. Pour obtenir une vue d’ensemble générale d’ACX et de la liste des termes ACX, consultez la vue d’ensemble des extensions de classe audio ACX.

Comme décrit dans Résumé des objets ACX, un objet AcxCircuit représente un chemin audio partiel ou complet vers un appareil audio perçu par l’utilisateur (haut-parleurs, micro, etc.). Un acxCircuit a au moins une broche d’entrée et une broche de sortie (ACXPIN), et peut agréger un ou plusieurs acxElements comme des objets. Le circuit représente un point de terminaison existant et ses fonctionnalités.

AcX Stream est un composant de pilote créé pour représenter un flux audio, créé par un circuit. Le flux est composé d’une liste d’éléments créés en fonction des éléments du circuit parent. Un circuit stream est un circuit dans une architecture multi-pile (chemin audio partiel) qui interface directement avec le service de streaming en mode utilisateur supérieur. Un circuit principal est un circuit dans une architecture multi-pile (chemin audio partiel) qui donne l’identité de l’appareil de point de terminaison audio.

Remarque

Les en-têtes et bibliothèques ACX ne sont pas inclus dans la version WDK 10.0.22621.2428 (publiée le 24 octobre 2023), mais sont disponibles dans les versions précédentes, ainsi que les dernières versions (25000) Insider Preview de wdK. Pour plus d’informations sur les préversions de WDK, consultez Installation des versions préliminaires du Kit de pilotes Windows (WDK).

Identification du circuit ACX

Chaque circuit ACX a un identificateur de circuit. ACX définit les éléments suivants :

Nom (str), identifie de manière unique ce type d’appareil audio de circuit. Il est utilisé pour localiser le paramètre d’INF et fait partie du lien symbolique utilisé pour accéder à ce circuit à partir d’un appareil distant. Exemple : « Render0 », « Render1 » ou « Capture0 ».
Lien symbolique. Un lien symbolique est associé à tous les circuits exposés. Les clients utilisent ce lien symbolique pour ouvrir un chemin de communication avec l’appareil/le circuit.
ID de composant (guid) du circuit. Identifie de manière unique l’instance de circuit (spécifique au fournisseur). Il ne peut pas être utilisé dans les liaisons AcxCircuitTemplate si l’URI du circuit a été spécifié.
URI de composant du circuit (str). Identifie de manière unique l’instance de circuit (spécifique au fournisseur). Elle ne peut pas être utilisée dans les liaisons AcxCircuitTemplate si l’ID de circuit a été spécifié.
ID de composant (guid) de Circuit Factory. Identifie de manière unique l’instance de fabrique de circuit (spécifique au fournisseur). Elle ne peut pas être utilisée dans les liaisons AcxCircuitTemplate si l’URI Circuit Factory a été spécifié.
URI de composant de Circuit Factory (str). Identifie de manière unique l’instance de fabrique de circuit (spécifique au fournisseur). Elle ne peut pas être utilisée dans les liaisons AcxCircuitTemplate si l’ID Circuit Factory a été spécifié.

AcxCircuitCreate

La fonction AcxCircuitCreate est utilisée pour créer un ACXCIRCUIT. Structure ACXCIRCUIT_INIT opaque utilisée par la fonction AcxCircuitCreate. AcxCircuitInitAllocate est utilisé pour initialiser la structure ACXCIRCUIT_INIT.

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.

Composition du circuit ACX

ACX lie les circuits jusqu’à ce qu’ils forment un chemin audio complet. ACX utilise des liaisons audio pour connecter des circuits audio ensemble. Pour plus d’informations, consultez la composition multimodèle ACX.

Création dynamique de circuit ACX (à tout moment)

ACX peut créer un circuit dynamique à la demande. Pour ce faire, le pilote alloue une structure WDFDEVICE_INIT en appelant WdfPdoInitAllocate. Le pilote spécifie ensuite les rappels PnP/power qu’il souhaite recevoir et crée l’appareil. Le pilote instancie le nouveau périphérique/circuit en appelant AcxDeviceAddCircuitDevice. Pour plus d’informations, consultez l’énumération de l’appareil ACX.

Suppression dynamique du circuit ACX

Le pilote appelle AcxDeviceRemoveCircuitDevice pour supprimer le périphérique audio de la liste des appareils. Cela déclenche la séquence de mise sous tension sur l’entité de circuit/circuit ACX. L’appareil/le circuit est supprimé de façon asynchrone. Pour plus d’informations, consultez l’énumération de l’appareil ACX.

AcxDeviceRemoveCircuit et AcxDeviceDetachCircuit

Il existe deux façons courantes de gérer l’arrêt du circuit. AcxDeviceDetachCircuit ou AcxDeviceRemoveCircuit.

Si l’appelant appelle AcxDeviceDetachCircuit, il ne doit pas appeler AcxDeviceRemoveCircuit. Si le pilote appelant souhaite supprimer le circuit après AcxDeviceDetachCircuit, il doit utiliser WdfObjectDelete.

En appelant AcxDeviceRemoveCircuit , le pilote appelant indique à ACX de supprimer ce circuit et de le supprimer de l’appareil. Dans ce cas, il n’est pas nécessaire d’appeler WdfObjectDelete sur le circuit.

En résumé, AcxDeviceDetachCircuit signifie que le pilote possède la gestion de la durée de vie des objets de circuit, AcxDeviceRemoveCircuit signifie que le circuit sera supprimé et supprimé.

Pour obtenir des informations générales sur la gestion de la durée de vie des objets WDF, consultez Framework Object Life Cycle.

AcxDeviceRemoveCircuitDevice

Différent de l’arrêt de circuit décrit ci-dessus, AcxDeviceRemoveCircuitDevice est utilisé par le pilote audio pour supprimer un point de terminaison audio existant et peut être appelé à tout moment pendant le cycle de vie du pilote.

Les pilotes peuvent également choisir de toujours détruire et recréer des périphériques audio sur le 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 EvtDevicePrepareHardware/EvtDeviceReleaseHardware, et le nouveau circuit est recréé dans EvtDevicePrepareHardware. Le pilote supprime un circuit en annulant l’inscription du circuit (à l’aide d’AcxDeviceRemoveCircuit).

EvtAcxCircuitReleaseHardware (EVT_ACX_CIRCUIT_RELEASE_HARDWARE) fonction de rappel

Si un pilote a inscrit une fonction de rappel EvtAcxCircuitReleaseHardware, l’infrastructure l’appelle pendant les transitions suivantes :

Rééquilibrage des ressources
Suppression ordonnée
Suppression surprise

L’infrastructure ACX appelle la fonction de rappel EvtAcxCircuitReleaseHardware une fois que l’infrastructure WDF a cessé d’envoyer des demandes d’E/S à l’appareil, toutes les interruptions affectées à l’appareil ont été désactivées et déconnectées, et l’appareil a été désactivé.

L’infrastructure ACX appelle la fonction de rappel EvtAcxCircuitReleaseHardware avant que l’infrastructure WDF appelle la fonction de rappel EvtDeviceReleaseHardware du pilote.

Lorsque l’infrastructure appelle EvtAcxCircuitReleaseHardware, l’objet PDO de l’appareil existe toujours et peut être interrogé pour les informations d’appareil disponibles dans l’état hors tension, par exemple l’état de configuration PCI.

En outre, les ressources matérielles traduites que l’infrastructure fournit à EvtDeviceReleaseHardware sont toujours affectées à l’appareil. L’objectif principal de cette fonction de rappel est de libérer ces ressources et, en particulier, de dissocier les ressources mémoire que la fonction de rappel EvtAcxCircuitPrepareHardware du pilote a mappée. Le pilote peut également utiliser ce rappel pour effectuer toute autre activité de gestion ACXCIRCUIT qui peut être nécessaire à l’état de mise hors tension. En règle générale, toutes les autres opérations d’arrêt matériel doivent se produire dans la fonction de rappel EvtDeviceD0Exit du pilote.

L’infrastructure ACX appelle toujours la fonction de rappel EvtAcxCircuitReleaseHardware du pilote si la fonction de rappel EvtAcxCircuitPrepareHardware du pilote a été appelée, sauf si evtAcxCircuitPrepareHardware a renvoyé un code d’échec.

Pour plus d’informations sur les ressources matérielles, consultez Présentation des ressources matérielles.

EvtAcxFactoryCircuitReleaseHardware (EVT_ACX_FACTORY_CIRCUIT_RELEASE_HARDWARE) fonction de rappel

Lorsque l’infrastructure appelle EvtAcxFactoryCircuitReleaseHardware , l’objet PDO de l’appareil existe toujours et peut être interrogé pour obtenir des informations sur l’appareil disponibles dans l’état hors tension, par exemple l’état de configuration PCI.

L’infrastructure ACX appelle toujours la fonction de rappel EvtAcxFactoryCircuitReleaseHardware du pilote si la fonction de rappel EvtAcxFactoryCircuitPrepareHardware du pilote a été appelée, sauf si evtAcxFactoryCircuitPrepareHardware a renvoyé un code d’échec.

Pour plus d’informations sur la gestion des objets WDF et des circuits, consultez ACX WDF Driver Lifetime Management.