Implementieren der Audiomodulkommunikation

Artikel
06/15/2023

Ein Audiomodul ist ein eindeutiger Teil der Audioverarbeitungslogik, die 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 Release 1703 gibt es sowohl APIs als auch DDIs zur Unterstützung der Kommunikation von Universelle Windows-Plattform-Apps (UWP) und Kernelmodus-Gerätetreibern.

Dieses Thema enthält Informationen zum Implementieren der Audiomodulkommunikation 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 auf seine Vorlieben abzustimmen. Das Audiosubsystem kann verschiedene Komponenten wie audioverarbeitende Objekte auf dem Host, Hardware-DSP-Verarbeitung und spezielle Hardware wie einen smarten Verstärker (alles zusätzlich zum Audiocodec 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 sich miteinander zu integrieren und Informationen zwischen den einzelnen Komponenten zu senden. Vorhandene WIN32-Konfigurationsanwendungen würden dann diese privaten APIs nutzen.

Die Universelle Windows-Plattform (UWP) stellt eine Reihe von APIs bereit, mit denen eine einzelne Anwendung auf einer Vielzahl von Geräten ausgeführt werden kann. UWP hat auch ein neues Aussehen und Verhalten eingeführt, das zur Kundenerwartung für Anwendungen geworden ist, die auf Windows 10 ausgeführt werden. So viele OEMs möchten ihre Audiokonfigurationsanwendungen auf UWP erstellen. Ein Kernsicherheitsfeature von UWP (die AppContainer-Sandbox) verhindert jedoch die Kommunikation von einer Anwendung mit anderen Komponenten im Audiosubsystem. Dadurch werden die privaten APIs gerendert, die zuvor von Konfigurations-Apps in UWP verwendet wurden.

Ab Windows 10, Release 1703, ermöglicht die UWP-API für Audiomodule der Konfigurationsanwendung und der Benutzermoduskomponenten die Kommunikation mit Modulen in der Kernel- und Hardwareebene, die über einen neuen KS-Eigenschaftensatz erkannt werden können. Audio-IHV 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	Ein eindeutiger Teil der Audioverarbeitungslogik, die eine relativ atomische 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 bei der Arbeit mit Audiotreibern verwendet.

Begriff	Definition
OEM	Original Equipment Manufacturer
IHV	Unabhängiger Hardwareanbieter
ISV	Unabhängiger Softwarehersteller
HSA	Hardwareunterstützungsanwendung
UWP	Universelle Windows-Plattform
APO	Audioverarbeitungsobjekt
DSP	Digitale Signalverarbeitung

Aufbau

Audiomodule richten einen von Windows unterstützten Mechanismus ein, um Nachrichten zwischen Benutzermodus- und Kernelmodus-Audiokomponenten zu senden. Ein wichtiger Unterschied besteht darin, dass Audiomodule die Transportpipeline standardisieren. Das Kommunikationsprotokoll für diesen Transport wird nicht festgelegt, und das Protokoll wird von den ISVs und IHVs definiert. Die Absicht besteht darin, vorhandenen Designs von Drittanbietern die einfache Migration zu Audiomodulen mit sehr geringen Änderungen zu ermöglichen.

Die Audiomodul-API ermöglicht den Zugriff auf die Module über zwei verschiedene Zielmethoden: den KS-Wellenfilter und einen initialisierten KS-Pin (Stream). Die Platzierung und der Zugriff auf bestimmte Module sind implementierungsspezifisch.

HSAs und andere Anwendungen können nur über das Filterhandle auf die verfügbaren Module zugreifen. Die einzelnen APOs, die in einen Stream geladen werden, sind die einzigen Objekte, die Zugriff auf die Zieldatenstrom-Audiomodule haben.

Weitere Informationen zu APOs finden Sie unter Windows-Audioverarbeitungsobjekte.

Senden von Befehlen

Die Möglichkeit des Audiomodulclients zum Abfragen und Ändern von Parametern besteht darin, Befehle an die Audiomodule im Kernel und an die Hardwarekomponenten im Audiosubsystem zu senden. Die Befehlsstruktur der Audiomodule-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 für die gesendeten Nachrichten und die erwartete Antwort festzulegen.

Modulbenachrichtigungen an Audiomodulclients

Der Audio-Miniport hat auch eine Möglichkeit, Informationen an Audiomodulclients zu benachrichtigen und zu übergeben, wenn der Client Benachrichtigungen für ein bestimmtes Modul abonniert hat. Die in diesen Benachrichtigungen übergebenen Informationen werden nicht von der Audiomodul-API definiert, sondern vom ISV und/oder IHV definiert.

Aktivieren, Deaktivieren und Allgemeine Topologieinformationen

Die Audiomodule-APIs definieren, wie Befehle aufgelistet und an die Module gesendet werden. Die APIs definieren jedoch nicht explizit, wie Audiomodulclients bestimmte Module aktivieren oder deaktivieren können. Außerdem bietet es keine Möglichkeit für Clients, Topologieinformationen oder die Platzierung von Modulen in Relation zueinander zu finden. IHVs und ISVs können bestimmen, ob diese Funktionalität benötigt wird, und entscheiden, wie sie implementiert werden soll.

Der empfohlene Ansatz ist das Verfügbarmachen eines globalen Treibermoduls. Das globale Treibermodul verarbeitet benutzerdefinierte Befehle für diese topologiespezifischen Anforderungen.

Audiomodul-DDIs

Eigenschaften des Kernelstreamingaudiomoduls

Ein neuer KS-Eigenschaftssatz, der von KSPROPSETID_AudioModule identifiziert wird, wurde für drei spezifische Eigenschaften für Audiomodule definiert.

Ein PortCls-Miniporttreiber muss die Antwort für jede Eigenschaft direkt verarbeiten, 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

Unterstützung für die KSPROPERTY_AUDIOMODULE_DESCRIPTORS-Eigenschaft identifiziert den Treiber als audiomodulfähig. Die -Eigenschaft wird über das Filter- oder Pinhandle abgefragt, und ein KSPROPERTY-Objekt wird als Eingabepuffer für den DeviceIoControl-Aufruf übergeben. KSAUDIOMODULE_DESCRIPTOR wurde definiert, um jedes Modul innerhalb 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.

Befehl "Audiomodul"

Die Unterstützung für die eigenschaft KSPROPERTY_AUDIOMODULE_COMMAND 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 ein KSAUDIOMODULE_PROPERTY wird als Eingabepuffer für den DeviceIoControl-Aufruf übergeben. Ein Client kann optional zusätzliche Informationen direkt neben dem 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.

Geräte-ID für Audiomodulbenachrichtigungen

Unterstützung für die KSPROPERTY_AUDIOMODULE_NOTIFICATION_DEVICE_ID ist erforderlich, damit der Miniport Benachrichtigungen signalisiert und Informationen an Audiomodulclients übergeben kann. Die Lebensdauer dieser ID ist an die Lebensdauer des Audiogeräts gebunden, das für den Windows-Audiostapel verfügbar gemacht und aktiv ist. Die -Eigenschaft kann über den Filter- oder Pinhandle gesendet werden, und ein KSPROPERTY wird als Eingabepuffer für den DeviceIoControl-Aufruf übergeben.

Weitere Informationen finden Sie unter KSAUDIOMODULE_PROPERTY.

PortCls-Hilfsprogramm – Audiomodulbenachrichtigungen

Eine neue Portschnittstelle wurde hinzugefügt, um Treiberentwickler beim Senden von Benachrichtigungen an Audiomodulclients zu unterstützen.

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