Implementazione della comunicazione del modulo audio
Un modulo audio è una parte distinta della logica di elaborazione audio che esegue una funzione relativamente atomica. Un modulo audio può risiedere nel driver audio o in DSP audio. Un modulo audio di esempio è l'elaborazione audio basata su DSP.
A partire da Windows 10, versione 1703, sono disponibili api e DDI per supportare la comunicazione da app piattaforma UWP (Universal Windows Platform) (UWP) e driver di dispositivo in modalità kernel.
Questo argomento fornisce informazioni sull'implementazione della comunicazione del modulo audio nel driver del dispositivo kernel.
Per informazioni su come inviare comandi e ricevere notifiche di modifica dai moduli di dispositivo audio usando un'app UWP, vedi Configurare ed eseguire query sui moduli dei dispositivi audio.
Perché usare i moduli audio?
Gli OEM in genere raggruppano un'applicazione di configurazione nel proprio sistema che consente al cliente di controllare gli aspetti di questo sistema audio e ottimizzarlo in base alle proprie preferenze. Il sottosistema audio può contenere vari componenti, ad esempio oggetti di elaborazione audio su host, elaborazione DSP hardware e hardware specializzato, ad esempio un smart amp (tutto oltre al codec audio stesso). Nella maggior parte dei casi questi componenti vengono creati e venduti da fornitori diversi. Storicamente, gli IHD hanno creato le proprie API private per integrarsi tra loro e inviare informazioni tra i singoli componenti. Le applicazioni di configurazione WIN32 esistenti sfruttano quindi queste API private.
La piattaforma UWP (Universal Windows Platform) (UWP) fornisce un set di API che consentono l'esecuzione di una singola applicazione in un'intera gamma di dispositivi. La piattaforma UWP ha anche introdotto un nuovo aspetto che è diventato l'aspettativa dei clienti per le applicazioni in esecuzione in Windows 10. Così tanti OEM vogliono creare le applicazioni di configurazione audio in UWP. Tuttavia, una funzionalità di sicurezza di base della piattaforma UWP (sandbox AppContainer) impedisce la comunicazione da un'applicazione ad altri componenti nel sottosistema audio. In questo modo le API private usate in precedenza dalle app di configurazione non sono accessibili nella piattaforma UWP.
A partire da Windows 10, versione 1703, l'API UWP dei moduli audio consente all'applicazione di configurazione e ai componenti in modalità utente di comunicare con i moduli nel kernel e nel livello hardware individuabili tramite un nuovo set di proprietà KS. IHV audio e ISV possono scrivere applicazioni e servizi in grado di comunicare con i moduli hardware usando un'interfaccia ben definita fornita da Windows. Per altre informazioni sull'API dei moduli audio, vedere Spazio dei nomi Windows.Media.Devices
Definizioni di moduli audio
Queste definizioni sono specifiche dei moduli audio.
| Termine | Definizione |
|---|---|
| Modulo audio | Una parte distinta della logica di elaborazione audio che esegue una funzione relativamente atomica. Può risiedere nel driver audio o in DSP audio. Un modulo audio di esempio è un oggetto apo (Audio Processing Object). |
Definizioni audio comuni
Queste definizioni vengono in genere usate quando si usano driver audio.
| Termine | Definizione |
|---|---|
| HSA | Applicazione di supporto hardware |
| UWP | Piattaforma UWP (Universal Windows Platform) |
| APO | Oggetto elaborazione audio |
| DSP | Elaborazione di segnali digitali |
| Termine | Definizione |
|---|---|
| OEM | Produttore di apparecchiature originali |
| IHV | Fornitore di hardware indipendente |
| ISV | Fornitore di software indipendenti |
Architettura
I moduli audio inserisce un meccanismo supportato dal sistema operativo Windows per inviare messaggi tra i componenti audio in modalità utente e in modalità kernel. Una distinzione importante è che i moduli audio standardizzano la pipeline di trasporto. Non stabilisce il protocollo di comunicazione su tale trasporto e si basa sugli ISV e IHV per definire il protocollo. Lo scopo è consentire alle progettazioni di terze parti esistenti di eseguire facilmente la migrazione a moduli audio con pochissime modifiche.
Il diagramma mostra come i dati audio vengono trasmessi dalle applicazioni utente fino al driver audio tramite le API del modulo audio.
Sono presenti moduli di dispositivo e moduli di flusso, a seconda che siano accessibili da un processo client o da un apo in esecuzione in AudioDG usando l'interfaccia dei moduli di flusso fornita all'APO da AudioDG. Per informazioni generali sull'endgine audio e sul grafico del dispositivo audio (AudioDG), vedi Architettura audio di Windows.
Il driver invia una notifica a Windows.Media.Devices delle modifiche dei moduli tramite la funzione IoReportTargetDeviceChangeAsynchronous, che viene quindi trasformata in callback dall'API modules al processo client o all'APO.
L'API Modulo audio fornisce l'accesso ai moduli tramite due diversi metodi di destinazione: il filtro d'onda KS e un pin KS inizializzato (flusso). Il posizionamento e l'accesso a moduli specifici sono specifici dell'implementazione.
Gli HSA e altre applicazioni saranno in grado di accedere solo ai moduli disponibili tramite l'handle di filtro. Le singole API caricate in un flusso sono gli unici oggetti che avranno accesso ai moduli audio di destinazione del flusso. Per altre informazioni sulle API, vedere Oggetti di elaborazione audio di Windows.
Invio di comandi
La strada del client del modulo audio per eseguire query e modificare i parametri consiste nell'inviare comandi ai moduli audio nel kernel e nei componenti hardware nel sottosistema audio. La struttura dei comandi dell'API Moduli audio è definita in modo libero e formalizza la modalità di individuazione e identificazione dei moduli. Tuttavia, la struttura dettagliata dei comandi deve essere progettata e implementata dall'ISV coinvolto e dall'IHV per stabilire il protocollo per i messaggi che possono essere inviati e la risposta prevista.
Notifiche dei moduli ai client del modulo audio
Il miniport audio offre anche un modo per notificare e passare informazioni ai client del modulo audio se il client ha sottoscritto le notifiche in un modulo specifico. Le informazioni passate in queste notifiche non sono definite dall'API Modulo audio, ma definite dall'ISV e/o dall'IHV.
Abilitare, disabilitare e informazioni generali sulla topologia
Le API Moduli audio definiscono come enumerare e inviare comandi ai moduli. Tuttavia, le API non definiscono in modo esplicito il modo in cui i client del modulo audio possono abilitare o disabilitare moduli specifici. Inoltre, non stabilisce un modo per i client di trovare informazioni sulla topologia o il posizionamento dei moduli in relazione tra loro. IHVs e ISV possono determinare se questa funzionalità è necessaria e decidere come implementarla.
L'approccio consigliato è l'esposizione di un modulo driver globale. Il modulo driver globale gestirà i comandi personalizzati per queste richieste specifiche della topologia.
DDI del modulo audio
Proprietà del modulo audio di streaming del kernel
Un nuovo set di proprietà KS, identificato da KSPROPSETID_AudioModule, è stato definito per tre proprietà specifiche dei moduli audio.
Un driver miniport PortCls deve gestire direttamente la risposta per ogni proprietà perché non viene fornita alcuna interfaccia helper.
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;
Descrittori del modulo audio
Il supporto per la proprietà KSPROPERTY_AUDIOMODULE_DESCRIPTORS identifica il driver come compatibile con il modulo audio. La proprietà verrà sottoposta a query tramite l'handle del filtro o del pin e un KSPROPERTY viene passato come buffer di input per la chiamata DeviceIoControl. KSAUDIOMODULE_DESCRIPTOR è stato definito per descrivere ogni modulo all'interno dell'hardware audio. Una matrice di questi descrittori viene restituita in risposta a questa richiesta
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;
Per altre informazioni, vedere KSAUDIOMODULE_DESCRIPTOR.
Comando modulo audio
Il supporto per la proprietà KSPROPERTY_AUDIOMODULE_COMMAND consente ai client del modulo audio di inviare comandi personalizzati per eseguire query e impostare parametri nei moduli audio. La proprietà può essere inviata tramite l'handle di filtro o pin e un KSAUDIOMODULE_PROPERTY viene passato come buffer di input per la chiamata DeviceIoControl. Un client può facoltativamente inviare informazioni aggiuntive immediatamente adiacenti al KSAUDIOMODULE_PROPERTY nel buffer di input per inviare comandi personalizzati.
ksmedia.h:
#define AUDIOMODULE_MAX_DATA_SIZE 64000
typedef struct _KSPAUDIOMODULE_PROPERTY
{
KSPROPERTY Property;
GUID ClassId;
ULONG InstanceId;
} KSAUDIOMODULE_PROPERTY, *PKSPAUDIOMODULE_PROPERTY;
Per altre informazioni, vedere KSAUDIOMODULE_PROPERTY.
ID dispositivo di notifica del modulo audio
Il supporto per il KSPROPERTY_AUDIOMODULE_NOTIFICATION_DEVICE_ID è necessario per consentire al miniport di segnalare le notifiche e passare le informazioni ai client del modulo audio. La durata di questo ID è legata alla durata del dispositivo audio esposto e attivo allo stack audio di Windows. La proprietà può essere inviata tramite l'handle di filtro o pin e un KSPROPERTY viene passato come buffer di input per la chiamata DeviceIoControl.
Per altre informazioni, vedere KSAUDIOMODULE_PROPERTY.
Helper PortCls - Notifiche del modulo audio
È stata aggiunta una nuova interfaccia di porta per aiutare gli sviluppatori di driver a inviare notifiche ai client del modulo 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;
Per altre informazioni, vedi:
IPortClsNotifications::AllocNotificationBuffer
IPortClsNotifications::FreeNotificationBuffer
IPortClsNotifications::SendNotificationBuffer
Sequenza chiamante
Il miniport chiamerà la porta per creare e inviare la notifica. La sequenza di chiamate generale è illustrata in questo diagramma.
