Driver Implementation Details

This topic presents the implementation details for an audio driver that is developed for an audio adapter that is capable of processing hardware-offloaded audio streams.

In other words, this topic explains what Microsoft has done (starting with Windows 8) to support a driver that works with an audio adapter that is capable of processing hardware-offloaded audio. In the following sections, this topic also shows you what the driver must be capable of to support such an adapter.

A new Type GUID for node descriptors

If an audio adapter is capable of processing offloaded audio streams, the adapter’s audio driver exposes this capability by using a newly introduced node in the KS-filter for the adapter.

Each node in the path of the audio stream has a node descriptor, so for this new node the driver must set the Type GUID to KSNODETYPE_AUDIO_ENGINE. Here’s an example of how the driver could configure the node descriptor for this new node:

typedef struct _KSNODE_DESCRIPTOR {
  const KSAUTOMATION_TABLE *AutomationTable;    // drv specific
  const GUID               *Type;       // must be set to KSNODETYPE_AUDIO_ENGINE
  const GUID               *Name;       // drv specific (KSNODETYPE_AUDIO_ENGINE?)  
} KSNODE_DESCRIPTOR, *PKSNODE_DESCRIPTOR;

If the Name GUID is set to KSNODETYPE_AUDIO_ENGINE, then you must create a default name string for this node. You then add that string to ks.inf, so that during installation of the driver, the string can be used to populate the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\MediaCategories registry key.

The definition of the GUID for the new node type, KSNODETYPE_AUDIO_ENGINE, is as follows:

Code style
#define STATIC_KSNODETYPE_AUDIO_ENGINE\
    0x35caf6e4, 0xf3b3, 0x4168, 0xbb, 0x4b, 0x55, 0xe7, 0x7a, 0x46, 0x1c, 0x7e
DEFINE_GUIDSTRUCT("35CAF6E4-F3B3-4168-BB4B-55E77A461C7E", KSNODETYPE_AUDIO_ENGINE);
#define KSNODETYPE_AUDIO_ENGINE DEFINE_GUIDNAMED(KSNODETYPE_AUDIO_ENGINE)

For more information, see the ksmedia.h header file.

And based on the preceding information, a descriptor for a miniport node could look like the following:

PCNODE_DESCRIPTOR MiniportNodes[] =
{
    // KSNODE_WAVE_AUDIO_ENGINE
    {
        0,                          // Flags
        NULL,                       // AutomationTable
        &KSNODETYPE_AUDIO_ENGINE,   // Type  KSNODETYPE_AUDIO_ENGINE
        NULL                        // Name
    }
};

A new KS property set for audio engines

Starting with Windows 8, the KSPROPSETID_AudioEngine property set has been introduced to support hardware audio engines and hardware-offloaded audio processing. So the driver for an adapter that can process offloaded audio streams must support the properties in this new property set.

The new property set, KSPROPSETID_AudioEngine, is defined as follows:

#define STATIC_KSPROPSETID_AudioEngine\
    0x3A2F82DCL, 0x886F, 0x4BAA, 0x9E, 0xB4, 0x8, 0x2B, 0x90, 0x25, 0xC5, 0x36
DEFINE_GUIDSTRUCT("3A2F82DC-886F-4BAA-9EB4-082B9025C536", KSPROPSETID_AudioEngine);
#define KSPROPSETID_AudioEngine DEFINE_GUIDNAMED(KSPROPSETID_AudioEngine)

The names of the properties in this new property set are defined in the KSPROPERTY_AUDIOENGINE enum, and the driver must support these names.

Here are the new properties in the KSPROPSETID_AudioEngine property set:

KSPROPERTY_AUDIOENGINE_BUFFER_SIZE_RANGE

KSPROPERTY_AUDIOENGINE_DESCRIPTOR

KSPROPERTY_AUDIOENGINE_DEVICEFORMAT

KSPROPERTY_AUDIOENGINE_GFXENABLE

KSPROPERTY_AUDIOENGINE_LFXENABLE

KSPROPERTY_AUDIOENGINE_LOOPBACK_PROTECTION

KSPROPERTY_AUDIOENGINE_MIXFORMAT

KSPROPERTY_AUDIOENGINE_SUPPORTEDDEVICEFORMATS

KSPROPERTY_AUDIOENGINE_VOLUMELEVEL

Updates to the KSPROPSETID_ Audio property set

In addition to supporting the properties in the new KSPROPSETID_AudioEngine property set, the driver must also support the following existing properties in the KSPROPSETID_Audio property set:

KSPROPERTY_AUDIO_MUTE

KSPROPERTY_AUDIO_PEAKMETER

KSPROPERTY_AUDIO_VOLUMELEVEL

And to complete the implementation of driver support for hardware-offloaded audio processing, new properties have been added to the KSPROPSETID_ Audio property set.

Here are the new KSPROPSETID_ Audio properties:

KSPROPERTY_AUDIO_LINEAR_BUFFER_POSITION

KSPROPERTY_AUDIO_PRESENTATION_POSITION

KSPROPERTY_AUDIO_WAVERT_CURRENT_WRITE_POSITION

Port-class driver updates and glitch reporting

In addition to the support described in the preceding sections for hardware-offloaded audio processing, the Windows port-class driver has also been updated with "helper interfaces" to make it simple to develop a driver that can work with offloaded audio streams. And when such a driver detects glitches, there is a mechanism in place to allow the driver to report the glitch errors. The following topics provide more details about the helper interfaces and glitch reporting:

Helper Interfaces for Offloaded Audio Processing

Glitch Reporting for Offloaded Audio


Send comments about this topic to Microsoft