Audiomodulecommunicatie implementeren

Een audiomodule is een uniek onderdeel van de audioverwerkingslogica die een relatief atomische functie uitvoert. Een audiomodule bevindt zich mogelijk in het audiostuurprogramma of in de audio-DSP. Een voorbeeld van een audiomodule is op DSP gebaseerde audioverwerking.

Vanaf Windows 10 release 1703 zijn er zowel API's als DDIS's ter ondersteuning van communicatie vanuit UWP-apps (Universal Windows Platform) en stuurprogramma's voor kernelmodus.

Dit onderwerp bevat informatie over het implementeren van audiomodulecommunicatie in het kernelapparaatstuurprogramma.

Zie Modules voor het configureren en opvragen van audioapparaten voor informatie over het verzenden van opdrachten en het ontvangen van wijzigingsmeldingen van audioapparaatmodules met behulp van een UWP-app.

Waarom audiomodules gebruiken?

OEM's bundelen doorgaans een configuratietoepassing op hun systeem waarmee de klant aspecten van dit audiosysteem kan beheren en afstemmen op hun voorkeur. Het audiosubsysteem kan verschillende onderdelen bevatten, zoals audioverwerkingsobjecten op de host, hardware-DSP-verwerking en gespecialiseerde hardware zoals een slimme amp (allemaal naast de audiocodec zelf). In de meeste gevallen worden deze onderdelen gemaakt en verkocht door verschillende leveranciers. In het verleden hebben IHD's hun eigen privé-API's gemaakt om met elkaar te integreren en informatie tussen de afzonderlijke onderdelen te verzenden. Bestaande WIN32-configuratietoepassingen maken vervolgens gebruik van deze privé-API's.

Het Universal Windows Platform (UWP) biedt een set API's waarmee één toepassing kan worden uitgevoerd op een groot aantal apparaten. UWP heeft ook een nieuwe look-and-feel geïntroduceerd die de klantverwachting is geworden voor toepassingen die worden uitgevoerd in Windows 10. Zoveel OEM's willen hun audioconfiguratietoepassingen bouwen op UWP. Een kernbeveiligingsfunctie van UWP (de AppContainer-sandbox) voorkomt echter communicatie van een toepassing naar andere onderdelen in het audiosubsysteem. Hiermee worden de privé-API's weergegeven die eerder door configuratie-apps zijn gebruikt, niet toegankelijk in UWP.

Vanaf Windows 10 release 1703 kan de UWP-API voor audiomodules de onderdelen van de configuratietoepassing en de gebruikersmodus communiceren met modules in de kernel- en hardwarelaag die kunnen worden gedetecteerd via een nieuwe KS-eigenschappenset. Audio-IHV en ISV's kunnen toepassingen en services schrijven die met hun hardwaremodules kunnen communiceren met behulp van een goed gedefinieerde interface van Windows. Zie De naamruimte Windows.Media.Devices voor meer informatie over de API voor audiomodules

Audiomoduledefinities

Deze definities zijn specifiek voor audiomodules.

Termijn	Definitie
Audiomodule	Een uniek stukje audioverwerkingslogica dat een relatief atomische functie uitvoert. Kan zich in het audiostuurprogramma of in de audio-DSP bevinden. Een voorbeeld van een audiomodule is een APO (Audio Processing Object).

Algemene audiodefinities

Deze definities worden meestal gebruikt bij het werken met audiostuurprogramma's.

Termijn	Definitie
HSA	Hardwareondersteuningstoepassing
UWP (Universal Windows Platform)	Het Universele Windows-platform
APO	Audioverwerkingsobject
DSP	Digitale signaalverwerking

Termijn	Definitie
OEM	Fabrikant van originele apparatuur
IHV	Onafhankelijke hardwareleverancier
Onafhankelijke Softwareleverancier (ISV)	Onafhankelijke softwareleverancier

Architectuur

Audiomodules introduceren een mechanisme dat door het Windows-besturingssysteem wordt ondersteund voor het verzenden van berichten tussen audio-onderdelen in gebruikersmodus en kernelmodus. Een belangrijk onderscheid is dat audiomodules de transportpijplijn standaardiseren. Het stelt het communicatieprotocol niet vast via dat transport en is afhankelijk van de ISV's en IHD's om het protocol te definiëren. Het doel is om bestaande ontwerpen van derden toe te staan om eenvoudig te migreren naar audiomodules met zeer weinig wijzigingen.

In het diagram ziet u hoe audiogegevens van gebruikerstoepassingen naar het audiostuurprogramma stromen via de API's van de audiomodule.

Apparaatmodules en streammodules zijn aanwezig, afhankelijk van of ze toegankelijk zijn vanuit een clientproces of een APO die wordt uitgevoerd in AudioDG met behulp van de interface voor streammodules die vanuit AudioDG aan de APO is verstrekt. Zie Windows Audio Architecture voor algemene informatie over de audio-endgine en de audioapparaatgrafiek (AudioDG).

Het stuurprogramma meldt Windows.Media.Devices van moduleswijzigingen via de functie IoReportTargetDeviceChangeAsynchronous, die vervolgens wordt omgezet in callbacks van de modules-API naar het clientproces of APO.

De Audio Module-API biedt toegang tot de modules via twee verschillende doelmethoden: het KS-golffilter en een geïnitialiseerde KS-pin (stream). De plaatsing en toegang tot specifieke modules is implementatiespecifiek.

HSA's en andere toepassingen hebben alleen toegang tot de modules die beschikbaar zijn via de filtergreep. De afzonderlijke APO's die in een stream zijn geladen, zijn de enige objecten die toegang hebben tot de gerichte audiomodules van de stream. Zie Windows Audio Processing Objects voor meer informatie over API's.

Opdrachten verzenden

De mogelijkheid van de client voor audiomodules om query's uit te voeren en parameters te wijzigen, is door opdrachten te verzenden naar de audiomodules in de kernel- en hardwareonderdelen in het audiosubsysteem. De opdrachtstructuur van de Audio Modules-API wordt losjes gedefinieerd en formaliseert de manier waarop modules worden gedetecteerd en geïdentificeerd. De gedetailleerde opdrachtstructuur moet echter worden ontworpen en geïmplementeerd door de betrokken ISV en IHV om het protocol vast te stellen voor welke berichten kunnen worden verzonden en de verwachte reactie.

Modulemeldingen voor audiomoduleclients

De audio miniport heeft ook een manier om informatie door te geven aan audiomoduleclients als de client zich heeft geabonneerd op meldingen in een specifieke module. De informatie die in deze meldingen wordt doorgegeven, wordt niet gedefinieerd door de Audio Module-API, maar wordt gedefinieerd door de ISV en/of IHV.

Inschakelen, uitschakelen en algemene topologie-informatie

De API's voor audiomodules definiëren hoe u opdrachten opsommen en naar de modules verzendt. De API's definiëren echter niet expliciet hoe audiomoduleclients specifieke modules kunnen in- of uitschakelen. Het biedt ook geen manier voor cliënten om topologie-informatie of de plaatsing van modules ten opzichte van elkaar te vinden. IHD's en ISV's kunnen bepalen of deze functionaliteit nodig is en bepalen hoe deze moet worden geïmplementeerd.

De aanbevolen aanpak is het weergeven van een globale stuurprogrammamodule. De globale stuurprogrammamodule verwerkt aangepaste opdrachten voor deze topologiespecifieke aanvragen.

DDIs van audiomodule

Audiomodule-eigenschappen voor kernelstreaming

Er is een nieuwe KS-eigenschappenset gedefinieerd, geïdentificeerd door KSPROPSETID_AudioModule, voor drie eigenschappen die specifiek zijn voor audiomodules.

Een PortCls-minipoortstuurprogramma moet het antwoord voor elke eigenschap rechtstreeks afhandelen, omdat er geen helperinterface is opgegeven.

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;

Audiomodulebeschrijvingen

Ondersteuning voor de eigenschap KSPROPERTY_AUDIOMODULE_DESCRIPTORS identificeert het stuurprogramma als audiomodulebewust. De eigenschap wordt door de filter- of pingreep opgevraagd en er wordt een KSPROPERTY doorgegeven als invoerbuffer voor de DeviceIoControl-aanroep. KSAUDIOMODULE_DESCRIPTOR is gedefinieerd om elke module binnen de audiohardware te beschrijven. Een matrix van deze descriptors wordt geretourneerd als reactie op deze aanvraag

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;

Zie KSAUDIOMODULE_DESCRIPTOR voor meer informatie.

Audiomodule-opdracht

Met ondersteuning voor de eigenschap KSPROPERTY_AUDIOMODULE_COMMAND kunnen audiomoduleclients aangepaste opdrachten verzenden om query's uit te voeren en parameters in te stellen voor audiomodules. De eigenschap kan worden verzonden via de filter- of speldgreep en een KSAUDIOMODULE_PROPERTY wordt doorgegeven als invoerbuffer voor de DeviceIoControl-aanroep. Een client kan desgewenst aanvullende informatie direct naast de KSAUDIOMODULE_PROPERTY in de invoerbuffer verzenden om aangepaste opdrachten te verzenden.

ksmedia.h:

#define AUDIOMODULE_MAX_DATA_SIZE 64000

typedef struct _KSPAUDIOMODULE_PROPERTY
{
    KSPROPERTY Property;
    GUID       ClassId;
    ULONG      InstanceId;
} KSAUDIOMODULE_PROPERTY, *PKSPAUDIOMODULE_PROPERTY;

Zie KSAUDIOMODULE_PROPERTY voor meer informatie.

Apparaat-id voor audiomodulemeldingen

Ondersteuning voor de KSPROPERTY_AUDIOMODULE_NOTIFICATION_DEVICE_ID is vereist om de minipoort in staat te stellen meldingen te signaleren en informatie door te geven aan audiomoduleclients. De levensduur van deze id is gekoppeld aan de levensduur van het audioapparaat dat aan de Windows-audiostack wordt blootgesteld en actief is. De eigenschap kan worden verzonden via de filter- of speldgreep en een KSPROPERTY wordt doorgegeven als de invoerbuffer voor de DeviceIoControl-aanroep.

Zie KSAUDIOMODULE_PROPERTY voor meer informatie.

PortCls Helper - Audiomodulemeldingen

Er is een nieuwe poortinterface toegevoegd om stuurprogrammaontwikkelaars te helpen meldingen te verzenden naar audiomoduleclients.

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;

Zie voor meer informatie:

IPortClsNotifications

IPortClsNotifications::AllocNotificationBuffer

IPortClsNotifications::FreeNotificationBuffer

IPortClsNotifications::SendNotificationBuffer

Aanroepvolgorde

De minipoort roept hun poort aan om de melding te maken en te verzenden. De algemene aanroepvolgorde wordt weergegeven in dit diagram.