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.

Allgemeine Audiodefinitionen

Diese Definitionen werden in der Regel beim Arbeiten mit Audiotreibern verwendet.

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

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.