Implémentation de la communication des modules audio
Un module audio est une partie distincte de la logique de traitement audio effectuant une fonction relativement atomique. Un module audio peut résider dans le pilote audio ou dans le DSP audio. Un exemple de module audio serait le traitement audio basé sur DSP.
À partir de Windows 10, version 1703, il existe à la fois des API et des DDI pour prendre en charge la communication entre les applications Universal Windows Platform (UWP) et les pilotes de périphérique en mode noyau.
Cette rubrique fournit des informations sur l’implémentation de la communication des modules audio dans le pilote de périphérique en mode noyau.
Pour des informations sur la manière d’envoyer des commandes et de recevoir des notifications de changement des modules de périphériques audio en utilisant une application UWP, veuillez consulter la section Configurer et interroger les modules de périphériques audio.
Pourquoi utiliser des modules audio ?
Les OEMs incluent généralement une application de configuration sur leur système permettant au client de contrôler des aspects de ce système audio et de le régler selon ses préférences. Le sous-système audio peut contenir divers composants tels que des objets de traitement audio sur l’hôte, le traitement DSP matériel et des matériels spécialisés comme un amplificateur intelligent (en plus du codec audio lui-même). Dans la plupart des cas, ces composants sont créés et vendus par différents fournisseurs. Historiquement, les IHVs ont créé leurs propres API privées pour s’intégrer les uns aux autres et envoyer des informations entre les composants individuels. Les applications de configuration WIN32 existantes exploitent alors ces API privées.
La Universal Windows Platform (UWP) fournit un ensemble d’API permettant à une seule application de fonctionner sur une gamme étendue d’appareils. UWP a également introduit un nouveau look-and-feel qui est devenu l’attente du client pour les applications fonctionnant sous Windows 10. Ainsi, de nombreux OEM souhaitent construire leurs applications de configuration audio sur UWP. Cependant, une fonctionnalité de sécurité essentielle de UWP (le sandbox AppContainer) empêche la communication d’une application avec d’autres composants du sous-système audio. Cela rend les API privées précédemment utilisées par les applications de configuration inaccessibles dans UWP.
À partir de Windows 10, version 1703, l’API Audio Modules UWP permet à l’application de configuration et aux composants en mode utilisateur de communiquer avec les modules dans la couche noyau et matérielle qui sont détectables via un nouvel ensemble de propriétés KS. Les IHV et ISV audio peuvent écrire des applications et des services capables de communiquer avec leurs modules matériels en utilisant une interface bien définie fournie par Windows. Pour plus d’informations sur l’API des modules audio, consultez la section Windows.Media.Devices Namespace.
Définitions des modules audio
Ces définitions sont spécifiques aux modules audio.
| Terme | Définition |
|---|---|
| Module audio | Une partie distincte de la logique de traitement audio effectuant une fonction relativement atomique. Peut résider dans le pilote audio ou dans le DSP audio. Un exemple de module audio serait un objet de traitement audio (APO). |
Définitions audio communes
Ces définitions sont généralement utilisées lors de la manipulation des pilotes audio.
| Terme | Définition |
|---|---|
| HSA | Application de support matériel |
| UWP | Plateforme Windows universelle |
| APO | Objet de traitement audio |
| DSP | Traitement du signal numérique |
| Terme | Définition |
|---|---|
| OEM | Fabricant d'équipements d'origine |
| IHV | Fournisseur de matériel indépendant |
| Fournisseurs de logiciels indépendants | Éditeur de logiciels indépendant |
Architecture
Modules audio met en place un mécanisme pris en charge par le système d’exploitation Windows pour envoyer des messages entre les composants audio en mode utilisateur et en mode noyau. Une distinction importante est que les modules audio standardisent le pipeline de transport. Ils n’établissent pas le protocole de communication sur ce transport et comptent sur les ISV et les IHV pour définir le protocole. L’objectif est de permettre aux conceptions tierces existantes de migrer facilement vers les modules audio avec très peu de modifications.
Le schéma montre comment les données audio circulent des applications utilisateur jusqu’au pilote audio via les API du module audio.
Les modules de périphérique et les modules de flux sont présents, selon qu’ils sont accessibles depuis un processus client ou un APO s’exécutant dans AudioDG en utilisant l’interface de modules de flux fournie à l’APO par AudioDG. Pour des informations générales sur le moteur audio et le graphe de périphériques audio (AudioDG), veuillez consulter la section Architecture audio de Windows.
Le pilote notifie Windows.Media.Devices des changements de modules via la fonction IoReportTargetDeviceChangeAsynchronous, qui est ensuite convertie en rappels de l’API des modules vers le processus client ou l’APO.
L’API des modules audio permet d’accéder aux modules via deux méthodes de ciblage différentes : le filtre KS wave et une broche KS initialisée (stream). Le placement et l’accès aux modules spécifiques sont spécifiques à l’implémentation.
Les HSA et autres applications ne pourront accéder qu’aux modules disponibles via la poignée du filtre. Les APO individuels chargés sur un flux sont les seuls objets qui auront accès aux modules audio ciblés par le flux. Pour plus d’informations sur les APO, consultez la section Windows Audio Processing Objects.
Envoi de commandes
Le moyen pour le client du module audio de interroger et modifier des paramètres est d’envoyer des commandes aux modules audio dans les composants noyau et matériels du sous-système audio. La structure de commande de l’API des modules audio est vaguement définie et formalise la manière dont les modules sont découverts et s’identifient. Cependant, la structure détaillée des commandes doit être conçue et implémentée par les ISV et IHV impliqués pour établir le protocole des messages qui peuvent être envoyés et la réponse attendue.
Notifications de module aux clients du module audio
Le miniport audio a également un moyen de notifier et de transmettre des informations aux clients du module audio si le client s’est abonné aux notifications sur un module spécifique. Les informations transmises dans ces notifications ne sont pas définies par l’API du module audio, elles sont définies par l’ISV et/ou l’IHV.
Activation, désactivation et informations générales sur la topologie
Les API des modules audio définissent comment énumérer et envoyer des commandes aux modules. Cependant, les API ne définissent pas explicitement comment les clients du module audio peuvent activer ou désactiver des modules spécifiques. De plus, elles n’établissent pas de moyen pour les clients de trouver des informations sur la topologie ou le placement des modules les uns par rapport aux autres. Les IHV et ISV peuvent déterminer si cette fonctionnalité est nécessaire et décider comment l’implémenter.
L’approche recommandée est d’exposer un module de pilote global. Le module de pilote global gérerait les commandes personnalisées pour ces demandes spécifiques à la topologie.
DDIs des modules audio
Propriétés des modules audio de Kernel Streaming
Un nouvel ensemble de propriétés KS, identifié par KSPROPSETID_AudioModule, a été défini pour trois propriétés spécifiques aux modules audio.
Un pilote de miniport PortCls doit gérer directement la réponse pour chaque propriété car aucune interface d’aide n’est fournie.
ksmedia.h :
#define STATIC_KSPROPSETID_AudioModule \
0xc034fdb0, 0xff75, 0x47c8, 0xaa, 0x3c, 0xee, 0x46, 0x71, 0x6b, 0x50, 0xc6
DEFINE_GUIDSTRUCT("C034FDB0-FF75-47C8-AA3C-EE46716B50C6", KSPROPSETID_AudioModule);
#define KSPROPSETID_AudioModule DEFINE_GUIDNAMED(KSPROPSETID_AudioModule)
typedef enum {
KSPROPERTY_AUDIOMODULE_DESCRIPTORS = 1,
KSPROPERTY_AUDIOMODULE_COMMAND = 2,
KSPROPERTY_AUDIOMODULE_NOTIFICATION_DEVICE_ID = 3,
} KSPROPERTY_AUDIOMODULE;
Descripteurs de modules audio
La prise en charge de la propriété KSPROPERTY_AUDIOMODULE_DESCRIPTORS identifie le pilote comme étant conscient des modules audio. La propriété sera interrogée via la poignée du filtre ou de la broche et une KSPROPERTY est passée comme tampon d’entrée pour l’appel DeviceIoControl. KSAUDIOMODULE_DESCRIPTOR a été défini pour décrire chaque module au sein du matériel audio. Un tableau de ces descripteurs est retourné en réponse à cette demande.
ksmedia.h :
#define AUDIOMODULE_MAX_NAME_SIZE 128
typedef struct _KSAUDIOMODULE_DESCRIPTOR
{
GUID ClassId;
ULONG InstanceId;
ULONG VersionMajor;
ULONG VersionMinor;
WCHAR Name[AUDIOMODULE_MAX_NAME_SIZE];
} KSAUDIOMODULE_DESCRIPTOR, *PKSAUDIOMODULE_DESCRIPTOR;
Pour plus d’informations, consultez la section KSAUDIOMODULE_DESCRIPTOR.
Commande de module audio
La prise en charge de la propriété KSPROPERTY_AUDIOMODULE_COMMAND permet aux clients des modules audio d’envoyer des commandes personnalisées pour interroger et définir des paramètres sur les modules audio. La propriété peut être envoyée via la poignée du filtre ou de la broche et un KSAUDIOMODULE_PROPERTY est passé comme tampon d’entrée pour l’appel DeviceIoControl. Un client peut éventuellement envoyer des informations supplémentaires immédiatement adjacentes à KSAUDIOMODULE_PROPERTY dans le tampon d’entrée pour envoyer des commandes personnalisées.
ksmedia.h :
#define AUDIOMODULE_MAX_DATA_SIZE 64000
typedef struct _KSPAUDIOMODULE_PROPERTY
{
KSPROPERTY Property;
GUID ClassId;
ULONG InstanceId;
} KSAUDIOMODULE_PROPERTY, *PKSPAUDIOMODULE_PROPERTY;
Pour plus d’informations, consultez la section KSAUDIOMODULE_PROPERTY.
ID de périphérique de notification du module audio
La prise en charge de la propriété KSPROPERTY_AUDIOMODULE_NOTIFICATION_DEVICE_ID est nécessaire pour permettre au miniport de signaler des notifications et de transmettre des informations aux clients des modules audio. La durée de vie de cet ID est liée à la durée de vie du périphérique audio exposé et actif dans la pile audio Windows. La propriété peut être envoyée via la poignée du filtre ou de la broche et une KSPROPERTY est passée comme tampon d’entrée pour l’appel DeviceIoControl.
Pour plus d’informations, consultez la section KSAUDIOMODULE_PROPERTY.
PortCls Helper : Notifications des modules audio
Une nouvelle interface de port a été ajoutée pour aider les développeurs de pilotes à envoyer des notifications aux clients des modules audio.
PortCls.h :
typedef struct _PCNOTIFICATION_BUFFER
{
UCHAR NotificationBuffer[1];
} PCNOTIFICATION_BUFFER, *PPCNOTIFICATION_BUFFER;
DECLARE_INTERFACE_(IPortClsNotifications,IUnknown)
{
DEFINE_ABSTRACT_UNKNOWN() // For IUnknown
STDMETHOD_(NTSTATUS, AllocNotificationBuffer)
( THIS_
_In_ POOL_TYPE PoolType,
_In_ USHORT NumberOfBytes,
_Out_ PPCNOTIFICATION_BUFFER* NotificationBuffer
) PURE;
STDMETHOD_(void, FreeNotificationBuffer)
( THIS_
_In_ PPCNOTIFICATION_BUFFER NotificationBuffer
) PURE;
STDMETHOD_(void, SendNotificationBuffer)
( THIS_
_In_ const GUID* NotificationId,
_In_ PPCNOTIFICATION_BUFFER NotificationBuffer
) PURE;
};
//
// Audio module notification definitions.
//
#define STATIC_KSNOTIFICATIONID_AudioModule \
0x9C2220F0, 0xD9A6, 0x4D5C, 0xA0, 0x36, 0x57, 0x38, 0x57, 0xFD, 0x50, 0xD2
DEFINE_GUIDSTRUCT("9C2220F0-D9A6-4D5C-A036-573857FD50D2", KSNOTIFICATIONID_AudioModule);
#define KSNOTIFICATIONID_AudioModule DEFINE_GUIDNAMED(KSNOTIFICATIONID_AudioModule)
typedef struct _KSAUDIOMODULE_NOTIFICATION {
union {
struct {
GUID DeviceId;
GUID ClassId;
ULONG InstanceId;
ULONG Reserved;
} ProviderId;
LONGLONG Alignment;
};
} KSAUDIOMODULE_NOTIFICATION, *PKSAUDIOMODULE_NOTIFICATION;
Pour plus d’informations, consultez l’article suivant :
IPortClsNotifications::AllocNotificationBuffer
IPortClsNotifications::FreeNotificationBuffer
IPortClsNotifications::SendNotificationBuffer
Séquence d’appel
Le miniport appellera son port pour créer et envoyer la notification. La séquence d’appel générale est montrée dans ce diagramme.
