Implementación de la comunicación del módulo de audio
Un módulo de audio es una parte distinta de la lógica de procesamiento de audio que realiza una función relativamente atómica. Un módulo de audio puede residir en el controlador de audio o en el DSP de audio. Un módulo de audio de ejemplo sería el procesamiento de audio basado en DSP.
A partir de Windows 10, versión 1703, hay API y DDI que incluyen comunicaciones de aplicaciones de la Plataforma universal de Windows (UWP) y controladores de dispositivos en modo kernel.
En este tema se da información sobre cómo implementar las comunicaciones del módulo de audio en el controlador de dispositivo basado en kernel.
Para obtener información sobre cómo enviar comandos y recibir notificaciones de cambios de módulos de dispositivos de audio mediante una aplicación de UWP, consulte Configuración y consultas de módulos de dispositivos de audio.
¿Por qué usar módulos de audio?
Normalmente, los OEM agrupan una aplicación de configuración en su sistema que permite al cliente controlar los aspectos de este sistema de audio y ajustarlos según sus preferencias. El subsistema de audio puede contener varios componentes, como objetos de procesamiento de audio en host, procesamiento de DSP de hardware y hardware especializado, como un amplificador inteligente (todo ello además del propio códec de audio). En la mayoría de casos, estos componentes los crean y venden diferentes proveedores. Como norma general, los IHV han creado sus propias API privadas para integrarse entre sí y enviar información entre cada uno de los componentes. Las aplicaciones de configuración WIN32 existentes aprovecharían estas API privadas.
La Plataforma universal de Windows (UWP) ofrece un conjunto de API que permiten que una sola aplicación se ejecute en una amplia variedad de dispositivos. UWP también incorporó un nuevo estilo que se ha convertido en la expectativa de los clientes para las aplicaciones que se ejecutan en Windows 10. Son muchos los OEM que quieren compilar sus aplicaciones de configuración de audio en UWP. Sin embargo, hay una función de seguridad básica de UWP (el espacio aislado AppContainer) que impide la comunicación de una aplicación con otros componentes del subsistema de audio. Esto representa las API privadas usadas anteriormente por las aplicaciones de configuración inaccesibles en UWP.
A partir de Windows 10, versión 1703, la API de UWP para módulos de audio permite que la aplicación de configuración y los componentes del modo de usuario se comuniquen con los módulos en la capa de kernel y de hardware, que se pueden detectar a través de un nuevo grupo de propiedades de KS. Los IHV e ISV de audio pueden escribir aplicaciones y servicios que pueden comunicarse con sus módulos de hardware mediante una interfaz bien definida facilitada por Windows. Para obtener más información sobre las API de módulos de audio, consulte Espacio de nombres Windows.Media.Devices.
Definiciones de módulos de audio
Estas definiciones son específicas de los módulos de audio.
| Término | Definición |
|---|---|
| Módulo de audio | Una parte distinta de la lógica de procesamiento de audio que realiza una función relativamente atómica. Puede residir en el controlador de audio o en el DSP de audio. Un módulo de audio de ejemplo sería un objeto de procesamiento de audio (APO). |
Definiciones de audio comunes
Estas definiciones se suelen usar al trabajar con controladores de audio.
| Término | Definición |
|---|---|
| HSA | Aplicación de soporte de hardware |
| UWP | Plataforma universal de Windows |
| APO | Objeto de procesamiento de audio |
| DSP | Procesamiento de señal digital |
| Término | Definición |
|---|---|
| OEM | Fabricante del equipo original |
| IHV | Proveedor de hardware independiente |
| ISV | Proveedor independiente de software |
Arquitectura
Los módulos de audio colocan un mecanismo compatible con el SO Windows para enviar mensajes entre el modo de usuario y los componentes de audio en modo kernel. La diferencia importante es que los módulos de audio normalizan el proceso de transporte. No establece el protocolo de comunicación sobre ese transporte y confía en los ISV e IHV para definir el protocolo. La finalidad es permitir que los diseños de terceros existentes migren fácilmente a módulos de audio con muy pocos cambios.
En el diagrama se muestra cómo fluyen los datos de audio desde las aplicaciones de usuario hasta el controlador de audio a través de las API del módulo de audio.
Los módulos de dispositivo y los módulos de transmisión están presentes, en función de si se accede a ellos desde un proceso de cliente o desde un APO que se ejecuta en AudioDG mediante la interfaz de módulos de transmisión proporcionada al APO desde AudioDG. Para obtener información general sobre el motor de audio y el gráfico de dispositivos de audio (AudioDG), consulte Arquitectura de audio de Windows.
El controlador notifica a Windows.Media.Devices los cambios de los módulos a través de la función IoReportTargetDeviceChangeAsynchronous, que luego se convierte en devoluciones de llamada de la API de módulos al proceso de cliente o APO.
La API de módulo de audio otorga acceso a los módulos a través de dos métodos de destino diferentes: el filtro de onda de KS y un pin de KS inicializado (transmisión). La ubicación y el acceso a módulos concretos son específicos de la implementación.
Las HSA y otras aplicaciones solo pueden acceder a los módulos disponibles a través del identificador de filtro. Cada uno de los APO cargados en una transmisión son los únicos objetos que tendrán acceso a los módulos de audio de destino de la transmisión. Para obtener más información sobre los APO, consulte Objetos de procesamiento de audio de Windows.
Envío de comandos
La vía del cliente del módulo de audio para consultar y cambiar parámetros se basa en enviar comandos a los módulos de audio en los componentes de kernel y hardware del subsistema de audio. La estructura de comandos de la API de módulos de audio se define de forma flexible y formaliza la manera en que se detectan e identifican los módulos. Sin embargo, la estructura de comandos detallada debe diseñarse e implementarse a través del ISV y del IHV implicados para establecer el protocolo para determinar qué mensajes se pueden enviar y cuál es la respuesta esperada.
Notificaciones de módulo a clientes de módulos de audio
El minipuerto de audio también tiene una manera de notificar y pasar información a los clientes de módulos de audio si el cliente tiene activadas las notificaciones en un módulo específico. La información que se pasa en estas notificaciones no está definida por la API de módulos de audio, sino que la define el ISV o el IHV.
Habilitación, deshabilitación e información general de la topología
Las API de módulos de audio definen cómo enumerar y enviar comandos a los módulos. Sin embargo, las API no definen expresamente cómo los clientes de módulos de audio pueden habilitar o deshabilitar módulos específicos. Además, no establece una manera de que los clientes encuentren información de la topología o la ubicación de los módulos en relación entre sí. Los IHV e ISV pueden determinar si se necesita esta funcionalidad y decidir cómo implementarla.
El método recomendado es exponer un módulo de controlador global. El módulo de controlador global controlaría los comandos personalizados para estas solicitudes específicas de topología.
DDI de módulos de audio
Propiedades de módulos de audio para streaming de kernel
Se ha definido un nuevo conjunto de propiedades de KS, identificado por KSPROPSETID_AudioModule para tres propiedades específicas para los módulos de audio.
Un controlador minipuerto PortCls debe controlar directamente la respuesta de cada propiedad, ya que no se facilita ninguna interfaz auxiliar.
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;
Descriptores de módulos de audio
La inclusión de la propiedad KSPROPERTY_AUDIOMODULE_DESCRIPTORS identifica el controlador como compatible con el módulo de audio. Se pueden hacer una consulta de la propiedad a través del identificador de pin o filtro y se pasa un KSPROPERTY como búfer de entrada para la llamada a DeviceIoControl. Se ha definido KSAUDIOMODULE_DESCRIPTOR para describir cada módulo dentro del hardware de audio. Se devuelve una matriz de estos descriptores en respuesta a esta solicitud.
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;
Para obtener más información, consulte KSAUDIOMODULE_DESCRIPTOR.
Comando de módulo de audio
La inclusión de la propiedad KSPROPERTY_AUDIOMODULE_COMMAND permite a los clientes del módulo de audio enviar comandos personalizados para consultar y ajustar parámetros en módulos de audio. La propiedad se puede enviar a través del controlador de pin o filtro y se pasa un KSAUDIOMODULE_PROPERTY como búfer de entrada para la llamada a DeviceIoControl. Está la opción de que un cliente pueda enviar información adicional inmediatamente adyacente a KSAUDIOMODULE_PROPERTY en el búfer de entrada para enviar comandos personalizados.
ksmedia.h:
#define AUDIOMODULE_MAX_DATA_SIZE 64000
typedef struct _KSPAUDIOMODULE_PROPERTY
{
KSPROPERTY Property;
GUID ClassId;
ULONG InstanceId;
} KSAUDIOMODULE_PROPERTY, *PKSPAUDIOMODULE_PROPERTY;
Para obtener más información, consulte KSAUDIOMODULE_PROPERTY.
ID de dispositivo para notificación del módulo de audio
Es necesario incluir el KSPROPERTY_AUDIOMODULE_NOTIFICATION_DEVICE_ID para que el minipuerto reciba las notificaciones y pase información a los clientes del módulo de audio. La duración de este identificador está vinculada a la duración del dispositivo de audio que se expone y que está activo en la pila de audio de Windows. La propiedad se puede enviar a través del controlador de pin o filtro y se pasa un KSPROPERTY como búfer de entrada para la llamada a DeviceIoControl.
Para obtener más información, consulte KSAUDIOMODULE_PROPERTY.
Asistente de PortCls: Notificaciones de módulos de audio
Se ha agregado una nueva interfaz de puerto para ayudar a los desarrolladores de controladores a enviar notificaciones a los clientes sobre los módulos de 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;
Para más información, vea:
IPortClsNotifications::AllocNotificationBuffer
IPortClsNotifications::FreeNotificationBuffer
IPortClsNotifications::SendNotificationBuffer
Secuencia de llamadas
El minipuerto llamará al puerto para crear y enviar la notificación. La secuencia de llamadas generales se muestra en este diagrama.
