Implementieren der Kommunikation von Audiomodulen
Ein Audiomodul ist ein unterschiedliches Element der Audioverarbeitungslogik, das eine relativ atomare Funktion ausführt. Ein Audiomodul kann sich im Audiotreiber oder im Audio-DSP befinden. Ein Beispiel für ein Audiomodul wäre die DSP-basierte Audioverarbeitung.
Ab Windows 10, Version 1703, gibt es sowohl APIs als auch DDIs zur Unterstützung der Kommunikation von UWP-Apps (Universal Windows Platform) und Gerätetreibern im Kernelmodus.
Dieses Thema enthält Informationen zur Implementierung der Kommunikation von Audiomodulen im Kernelgerätetreiber.
Informationen zum Senden von Befehlen und Empfangen von Änderungsbenachrichtigungen von Audiogerätemodulen mithilfe einer UWP-App finden Sie unter Konfigurieren und Abfragen von Audiogerätemodulen.
Gründe für die Verwendung von Audiomodulen
OEMs bündeln in der Regel eine Konfigurationsanwendung auf ihrem System, die es dem Kunden ermöglicht, Aspekte dieses Audiosystems zu steuern und es nach seinen Wünschen abzustimmen. Das Audio-Subsystem kann verschiedene Komponenten wie Audioverarbeitungsobjekte auf dem Host, Hardware-DSP-Verarbeitung und spezielle Hardware wie einen Smart Amp (alles zusätzlich zum Audio-Codec selbst) enthalten. In den meisten Fällen werden diese Komponenten von verschiedenen Anbietern erstellt und verkauft. In der Vergangenheit haben IHVs ihre eigenen privaten APIs erstellt, um sie miteinander zu integrieren und Informationen zwischen den einzelnen Komponenten zu senden. Vorhandene WIN32-Konfigurationsanwendungen würden dann diese privaten APIs nutzen.
Die Universal Windows Platform (UWP) stellt eine Reihe von APIs bereit, mit denen eine einzelne Anwendung auf einer Vielzahl von Geräten ausgeführt werden kann. UWP hat außerdem ein neues Erscheinungsbild eingeführt, das zu den Kundenerwartungen für Anwendungen unter Windows 10 geworden ist. So viele OEMs möchten ihre Audiokonfigurationsanwendungen auf der UWP erstellen. Ein Kernsicherheitsfeature von UWP (die AppContainer-Sandbox) verhindert jedoch die Kommunikation von einer Anwendung zu anderen Komponenten im Audiosubsystem. Dadurch werden die privaten APIs gerendert, die zuvor von Konfigurations-Apps verwendet wurden, auf die in UWP nicht zugegriffen werden kann.
Ab Windows 10, Version 1703, ermöglicht die UWP-API für Audiomodule die Kommunikation mit Modulen in der Kernel- und Hardwareebene, die über einen neuen KS-Eigenschaftensatz erkannt werden können. Audio-IHVs und ISVs können Anwendungen und Dienste schreiben, die über eine von Windows bereitgestellte klar definierte Schnittstelle mit ihren Hardwaremodulen kommunizieren können. Weitere Informationen zur Audiomodul-API finden Sie unter Windows.Media.Devices-Namespace
Audiomoduldefinitionen
Diese Definitionen sind spezifisch für Audiomodule.
| Begriff | Definition |
|---|---|
| Audiomodul | Eine eigenständige Audioverarbeitungslogik, die eine relativ atomare Funktion ausführt. Kann sich im Audiotreiber oder im Audio-DSP befinden. Ein Beispiel für ein Audiomodul wäre ein Audioverarbeitungsobjekt (APO). |
Allgemeine Audiodefinitionen
Diese Definitionen werden in der Regel beim Arbeiten mit Audiotreibern verwendet.
| Begriff | Definition |
|---|---|
| HSA | Hardwareunterstützungsanwendung |
| UWP | Universelle Windows-Plattform |
| APO | Audioverarbeitungsobjekt |
| DSP | Digitale Signalverarbeitung |
| Begriff | Definition |
|---|---|
| OEM | Original Equipment Manufacturer |
| IHV | Unabhängiger Hardwareanbieter |
| ISV | Unabhängiger Softwarehersteller |
Aufbau
Audio Modules stellt einen vom Windows-Betriebssystem unterstützten Mechanismus zum Senden von Nachrichten zwischen Audiokomponenten im Benutzermodus und im Kernelmodus bereit. Ein wichtiger Unterschied besteht darin, dass Audio Modules die Transportpipeline standardisiert Es erstellt kein Kommunikationsprotokoll über diesen Transport und verlässt sich bei der Definition des Protokolls auf die ISVs und IHVs. Ziel ist es, bestehende Designs von Drittanbietern mit sehr geringen Änderungen problemlos auf Audio Modules zu migrieren.
Das Diagramm zeigt, wie Audiodaten von Benutzeranwendungen über die Audiomodul-APIs zum Audiotreiber fließen.
Gerätemodule und Streammodule sind vorhanden, je nachdem, ob auf sie von einem Clientprozess aus oder von einem APO aus zugegriffen wird, das in AudioDG mithilfe der Streammodulschnittstelle ausgeführt wird, die AudioDG dem APO bereitstellt. Allgemeine Informationen zum Audiomodul und zum Audiogerätediagramm (Audio Device Graph, AudioDG) finden Sie unter Windows Audio-Architektur.
Der Treiber benachrichtigt Windows.Media.Devices mithilfe der IoReportTargetDeviceChangeAsynchronous-Funktion über die am Modul durchgeführten Änderungen, was anschließend in Rückrufe von der Modul-API zum Clientprozess oder zum APO umgewandelt wird.
Die Audiomodul-API bietet Zugriff auf die Module über zwei verschiedene Zielmethoden: den KS-Wave-Filter und einen initialisierten KS-Pin (Stream). Die Platzierung und der Zugriff auf bestimmte Module sind implementierungsspezifisch.
HSAs und andere Anwendungen können nur auf die Module zugreifen, die über den Filter-Handle verfügbar sind. Die einzelnen APOs, die in einen Stream geladen werden, sind die einzigen Objekte, die Zugriff auf die Ziel-Audiomodule des Streams haben. Weitere Informationen zu APOs finden Sie unter Windows-Audioverarbeitungsobjekte.
Senden von Befehlen
Die Möglichkeit des Audiomodul-Clients zum Abfragen und Ändern von Parametern besteht darin, Befehle an die Audiomodule im Kernel und an Hardwarekomponenten im Audio-Subsystem zu senden. Die Befehlsstruktur der Audiomodul-API ist lose definiert und formalisiert die Art und Weise, wie Module erkannt und identifiziert werden. Die detaillierte Befehlsstruktur muss jedoch vom beteiligten ISV und IHV entworfen und implementiert werden, um das Protokoll dafür festzulegen, welche Nachrichten gesendet werden können und welche Antwort erwartet wird.
Modulbenachrichtigungen für Audiomodulclients
Der Audio-Miniport bietet auch die Möglichkeit, Audiomodul-Clients zu benachrichtigen und ihnen Informationen zu übermitteln, wenn der Client Benachrichtigungen für ein bestimmtes Modul abonniert hat. Die in diesen Benachrichtigungen übergebenen Informationen werden nicht durch die Audiomodul-API definiert, sondern durch den ISV und/oder IHV.
Aktivieren, Deaktivieren und allgemeine Topologieinformationen
Die Audiomodul-APIs definieren das Aufzählen und Senden von Befehlen an die Module. Die APIs definieren jedoch nicht explizit, wie Audiomodulclients bestimmte Module aktivieren oder deaktivieren können. Außerdem gibt es für Clients keine Möglichkeit, Informationen zur Topologie oder zur Platzierung von Modulen zueinander zu finden. IHVs und ISVs können ermitteln, ob diese Funktionalität benötigt wird, und entscheiden, wie sie implementiert werden soll.
Der empfohlene Ansatz besteht darin, ein globales Treibermodul verfügbar zu geben. Das globale Treibermodul behandelt benutzerdefinierte Befehle für diese topologiespezifischen Anforderungen.
Audiomodul-DDIs
Eigenschaften des Kernelstreaming-Audiomoduls
Ein neuer KS-Eigenschaftensatz, der durch KSPROPSETID_AudioModule identifiziert wird, wurde für drei für Audiomodule spezifische Eigenschaften definiert.
Ein PortCls-Miniporttreiber muss die Antwort für jede Eigenschaft direkt behandeln, da keine Hilfsschnittstelle bereitgestellt wird.
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;
Audiomoduldeskriptoren
Die Unterstützung für die KSPROPERTY_AUDIOMODULE_DESCRIPTORS-Eigenschaft identifiziert den Treiber als Audiomodul-fähig. Die Eigenschaft wird über den Filter oder das Pin-Handle abgefragt und ein KSPROPERTY wird als Eingabepuffer für den DeviceIoControl-Aufruf übergeben. KSAUDIOMODULE_DESCRIPTOR wurde definiert, um jedes Modul in der Audiohardware zu beschreiben. Ein Array dieser Deskriptoren wird als Antwort auf diese Anforderung zurückgegeben.
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;
Weitere Informationen finden Sie unter KSAUDIOMODULE_DESCRIPTOR.
Audiomodulbefehl
Die Unterstützung für die KSPROPERTY_AUDIOMODULE_COMMAND-Eigenschaft ermöglicht es Audiomodulclients, benutzerdefinierte Befehle zum Abfragen und Festlegen von Parametern für Audiomodule zu senden. Die Eigenschaft kann über das Filter- oder Pinhandle gesendet werden, und eine KSAUDIOMODULE_PROPERTY wird als Eingabepuffer für den DeviceIoControl-Aufruf übergeben. Ein Client kann optional zusätzliche Informationen direkt neben der KSAUDIOMODULE_PROPERTY im Eingabepuffer senden, um benutzerdefinierte Befehle zu senden.
ksmedia.h:
#define AUDIOMODULE_MAX_DATA_SIZE 64000
typedef struct _KSPAUDIOMODULE_PROPERTY
{
KSPROPERTY Property;
GUID ClassId;
ULONG InstanceId;
} KSAUDIOMODULE_PROPERTY, *PKSPAUDIOMODULE_PROPERTY;
Weitere Informationen finden Sie unter KSAUDIOMODULE_PROPERTY.
ID des Audiomodulbenachrichtigungsgeräts
Unterstützung für die KSPROPERTY_AUDIOMODULE_NOTIFICATION_DEVICE_ID ist erforderlich, um den Miniport für Signalbenachrichtigungen zu aktivieren und Informationen an Audiomodul-Clients zu übergeben. Die Lebensdauer dieser ID ist an die Lebensdauer des Audiogeräts gebunden, das im Windows-Audiostapel verfügbar und aktiv ist. Die Eigenschaft kann über das Filter- oder Pinhandle gesendet werden, und eine KSPROPERTY wird als Eingabepuffer für den DeviceIoControl-Aufruf übergeben.
Weitere Informationen finden Sie unter KSAUDIOMODULE_PROPERTY.
PortCls-Hilfsprogramm – Audiomodulbenachrichtigungen
Um Treiberentwicklern das Senden von Benachrichtigungen an Audiomodulclients zu erleichtern, wurde eine neue Portschnittstelle hinzugefügt.
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;
Weitere Informationen finden Sie unter:
IPortClsNotifications::AllocNotificationBuffer
IPortClsNotifications::FreeNotificationBuffer
IPortClsNotifications::SendNotificationBuffer
Aufrufreihenfolge
Der Miniport ruft den Port auf, um die Benachrichtigung zu erstellen und zu senden. Die allgemeine Aufrufsequenz wird in diesem Diagramm angezeigt.
