WDM Audio Drivers
The Microsoft® Windows® family of operating systems include enhancements to simplify development and management of Windows Driver Model (WDM) streaming audio drivers. This paper provides a brief overview of the architecture and design direction for WDM audio under Windows 2000, using the Windows Driver Connection Streaming Architecture (WDM CSA). The Windows DDK documents the specific driver modifications required to allow current drivers to work in a Windows 2000/Windows XP operating system. For details about implementing WDM audio, see the Windows DDK.
===========================
Introduction
WDM is a robust model for driver implementation that is supported by the Windows family of operating systems; the WDM Connection Streaming Architecture (WDM CSA) is a media streaming architecture based on WDM. WDM CSA allows audio stream drivers to communicate directly with audio adapter hardware. Using this model, device driver writers can create one audio driver that works on Windows-based systems.
This article provides a brief overview of the architecture and design direction for WDM audio under Windows 2000/Windows XP.
===============================
Why WDM Audio?
WDM audio is designed to make writing hardware drivers for streaming devices simpler. Specifically, WDM audio provides the following functionality:
Rich baseline of audio features and quality implemented by operating system components. These features are available to end-users with minimal, if any, IHV driver development.
Optional routine synchronization and request serialization allow the miniport/minidriver to be multiprocessor safe and nonreentrant for low-end to medium-end hardware.
Correct file operation synchronization. For example, stream and device opens are correctly serialized without having the miniport/minidriver implement mutexes, semaphores, or events.
The WDM CSA pin implementation is abstracted from the miniport/minidriver.
Plug-and-Play functions and services are abstracted from the miniport/minidriver:
The class driver creates a functional device object.
Configuration is obtained from the Plug-and-Play enumerator, and all necessary processing is performed on the resources (port addresses translated, memory ranges translated and mapped, interrupt connected).
Plug-and-Play functions such as START, STOP, UNLOAD, and ADD DEVICE are abstracted.
The class driver handles all low-level buffer management:
It allocates DMA adapter object, as necessary.
It maps buffers and builds scatter/gather lists for DMA.
It locks and flushes buffers appropriately in DMA versus PIO cases.
The class driver performs all IOCTL parameter validation.
The class driver uses a watchdog timer to time all requests.
=======================
Background – WDM and WDM Connection Streaming Architecture (CSA)
Increasingly, the personal computer is used for applications that require streaming and synchronization of data. These applications differ from those used for traditional business tasks in that they deliver large amounts of data to hardware, and that data is generally time-sensitive. While the PC is making advances in these areas, implementation of streaming and synchronization has been hindered by an inconsistent driver model, an architecture that wasn’t modular or extensible, inefficient use of system resources, and inherent delivery delays (also known as system latency).
The first step in resolving these issues was to standardize the driver model. To this end, Microsoft developed WDM, which is an integral part of Windows 98 and Windows 2000. With WDM, drivers can be written once and then run on both Windows 98/Me and Windows 2000/Windows XP. WDM is based on the Windows NT layered device driver model and provides additional support for Plug-and-Play.
While this solves some of the problems, it does not address problems associated with monolithic drivers, data streaming inefficiencies, and stream delays. WDM CSA is built on top of WDM, and is designed to address these specific issues associated with time-sensitive applications.
WDM CSA presents drivers as filters through which media streams pass. A filter is a special kind of driver that incorporates a series of pins, which can be linked together to form systems of filters. Filters allow you to modify some aspects of an existing driver’s behavior without requiring you to rewrite the driver or the applications that use the driver.
The modular nature of WDM CSA allows you to add features or hide the limitations of a lower-level device driver. For example, you could add compression or encryption support to a device without modifying the underlying device driver or the programs that use that device. You can use a filter to divide large data into acceptable chunks before passing that data along to a driver that has transfer size limits. Filters also let you add or remove expensive behavior you do not want to include in a driver, such as performance monitoring. (Disk performance monitoring tools in Windows NT make use of this functionality.)
Filters have input pins that consume media streams, and output pins that produce media streams. In keeping with this model, audio adapters are manifested as filters. Input pins on these filters consume audio streams and route them to the audio hardware. Output pins on these filters produce audio streams from data produced by the hardware.
=======================
Architectural Overview
To make audio hardware drivers easier to write, the WDM audio driver model isolates hardware interface issues from streaming filter implementation issues. It accomplishes this by organizing the driver code into components that address these issues separately and by precisely defining the interfaces between these components. Note that all of the components are referred to as drivers, although not all are recognized as such by the operating system.
The following illustration provides a simplified view of WDM audio driver architecture for Windows 2000.
======================
Figure 1. Windows 2000 WDM Audio Architecture
Note that many of the component names shown in this illustration resemble those found in classic Windows NT driver architecture. However, WDM driver architecture uses some of these terms differently. The following paragraphs define these components as they are used in the WDM implementation of its own driver architecture, and points out some of the key differences between their WDM use and the classic Windows NT implementation.
------------------
Audio APIs
The audio application programming interfaces (APIs) are built on top of the WDM CSA driver architecture. These APIs include Microsoft DirectSound®, WinMM (for Win32® compatibility), and MMSystem (for Win16 compatibility).
DirectSound
The DirectSound API is the audio component of the DirectX® Programmer’s Reference of the Platform Software Development Kit (SDK). DirectSound provides low-latency mixing, hardware acceleration, and direct access to the sound device. It provides this functionality while maintaining compatibility with existing device drivers.
This release of DirectSound has capabilities for audio capture and support for property sets, which enable application developers to take advantage of extended services offered by sound cards and their associated drivers.
The overriding design goal in DirectX is speed. Like other components of DirectX, DirectSound allows you to use the hardware in the most efficient way possible while insulating you from the specific details of that hardware with a device-independent interface. Your applications will work well with the simplest audio hardware but will also take advantage of the special features of cards and drivers that have been enhanced for use with DirectSound.
DirectSound simplifies the following:
Querying hardware capabilities at run time to determine the best solution for any given personal computer configuration
Using property sets so that new hardware capabilities can be exploited even when they are not directly supported by DirectSound
Low-latency mixing of audio streams for rapid response
Developing 3-D sound
Capturing sound
-------------------
Kmixer
Two operating system components perform the work of combining audio streams. The system audio device (SysAudio.sys) is responsible for selecting the path for the successful formatting, sample rate conversion (SRC), and mixing necessary to combine digital streams. The kernel mixer (or KMixer) performs the actual operation. KMixer allows the intelligent selection or output rate based on quality versus CPU usage, and allows all streams or individual streams to be played. It supports mono, stereo, and multichannel (5.1, 7.1) streams based on renderer technology, and it performs synchronization and SRC as necessary. The SRC performed by Kmixer is a high quality, high performance multitap FIR based SRC that meets the current PC System Design Guide guidelines for Advanced Audio quality sound-to-noise ratio (SNR).
These two components permit multiple audio applications to play sound simultaneously. For example, you can hear everything while simultaneously playing a DVD movie, a DirectX-based game, and (on Windows 98 systems) an MS-DOS-based game. When e-mail arrives, you will hear the alert sound.
-----------------------
Port Class and Miniport Drivers vs. Stream Class Driver and Minidriver
Windows 2000 supports three different hardware types: Plug-and-Play ISA, PCI, and USB audio. To support these different hardware specifications, Windows 2000 provides two distinct driver models:
Port Class Miniport Driver. All PCI and ISA devices should use a port class/miniport driver pair.
Stream Class Minidrivers. USB audio devices should use a stream class driver and a minidriver.
The next sections discuss these two models in greater detail. (Refer to Figure 1 for a simplified view of the architecture.)
---------------------
WDM Audio Port Class/Miniport Driver Model (PCI and ISA)
The following components are used in the WDM audio port class/miniport driver model:
Port Driver. The port driver implements a WDM streaming filter on behalf of a miniport and operates in the context of a port class driver. It is responsible for adapter-independent code and for exposing a miniport’s function-specific code as a WDM streaming filter to the system.
Port Class Driver. The port class driver (identified in the illustration as PortCls.Sys) is essentially a container for a set of port drivers. At the request of the adapter driver, it binds together the port drivers, miniport drivers, and hardware resources to form a complete subdevice. The port class driver also:
Coordinates the operation of these subdevices to form a complete device corresponding to the audio adapter hardware.
Provides a set of helper functions to adapter drivers and miniport drivers.
Resides in a .SYS file, but is not loaded in the way a driver is loaded, it is an "export driver."
The port class driver does not fit the classic Windows NT model because it is responsible for allowing multiple port/miniport bindings to share a single device object. The port class driver also provides helper functionality to port and miniport drivers.
Miniport Driver. A WDM audio miniport implements a function-specific interface for a function on a specific adapter (for example, audio card). Miniport drivers are part of an adapter driver.
Adapter Driver. The adapter driver serves as a container for all miniport drivers associated with a given adapter. It is recognized as a driver by the operating system and is contained in its own .SYS file The adapter driver consists of a set of miniport drivers and additional code that addresses initialization issues.
A Microsoft-provided class driver is an intermediate driver designed to provide a simple interface between a vendor-written miniport driver and the operating system. A miniport driver is a hardware-specific DLL that uses a Microsoft-provided class driver to accomplish most actions through function calls, and provides only device-specific controls.
Under WDM, the miniport driver registers its associated hardware adapters with the class driver, and the class driver creates a file object to represent each port/miniport combination that registers. (The registration process is described in the reference section of the Microsoft DDK.) Each minidriver uses its paired class driver's device object to make support routines. The class driver is accessed by the outside world through WDM CSA.
The following is a list of miniport driver interfaces:
WaveCyclic Input and Output—This class of miniport drivers supports access to DMA-based wave I/O functions of ISA and other audio cards. The interface addresses cyclic (autoinit) DMA buffers specifically, leaving streaming issues to be solved by the port driver.
Scatter/Gather Wave Input and Output—This class of miniport drivers supports access to wave audio functions such as the wave I/O functions of a PCI audio card. In this model, lists of wave audio buffers are logically appended to create a stream of wave audio.
MIDI Input and Output—This class of miniport drivers supports access to MIDI-based functions such as FM synthesizers and UART-based hardware interfaces. Timing is handled by the port driver or some other component higher in the driver stack, allowing the miniport to concentrate on the immediate implementation or delivery of MIDI messages. MIDI devices that handle their own timing, such as MPU-401 coprocessors, require a specialized port driver and are not within the scope of this interface. This class of miniport drivers supports access to wave table synthesizer voices such as the ones supplied by the Creative Labs SoundBlaster AWE32 adapter. The interface allows for the transfer of static wave data to the adapter and for the manipulation of the voice parameters.
Topology—This class of miniport drivers supports access to the various controls (volume, equalization, and reverb) that audio adapters typically offer. The interface concerns itself with the enumeration of components (known as nodes) in the topology, the discovery of their interconnections, and the reading and writing of control parameters.
--------------------
WDM Audio Stream Class Driver and Minidriver Model (USB Audio)
The streaming minidriver is a peer of the class driver, and can call WDM support routines as necessary. The minidriver does not allocate a device object, however, and instead uses the class driver's device object to make support routines. Most minidrivers will not need to make WDM support routines, as all necessary functionality is available from the class driver.
Stream class is an appropriate class for audio driver development when the nature of the driver is either complex beyond our port support (existing, anticipated or not anticipated) or represents a class of devices with one driver (USB audio and 1394 audio for example). It is also appropriate for supporting some audio functionality in a driver that primarily supports other streaming functionality, such as MPEG2 and AC3 decode or video capture. The vast majority of audio independent hardware vendors (IHVs) should be using the port class/miniport driver model, but Microsoft provides the stream class/minidriver model to enable proprietary monolithic audio drivers and drivers for A/V devices with basic audio functionality.
--------------------
Audio Chip Detection
Methods for enumerating audio chips must comply with the current PC System Design Guide guidelines. PCI audio chips will be enumerated and configured by the PCI Bus driver using the PCI Bus Standard mechanisms. You should comply with the current PC System Design Guide Guidelines for PCI devices, including the Subsystem ID and Subsystem Vendor IDs. PCI devices must not use ISA-based resources.
The system must be capable of automatically assigning, disabling, and relocating the resources used by this device when necessary, using the method required for the related bus class. All configuration settings must be capable of being made through software, with no system boot required.
When the end user changes this device or adds it to the system, setting resource assignments must not require changing jumpers or switches on either the adapter or the system board. In the event of an irreconcilable conflict with other devices on the system, the system must be able to disable the device in order to prevent the system from stalling. The device must not claim any resources while disabled.
--------------------
Driver Installation
For sample INFs and details about installing WDM audio drivers, see the Windows DDK.
---------------------
Testing, Logo Program, and Hardware Support
The latest audio compatibility tests are available from Windows Hardware Quality Labs (WHQL).
--------------------
Summary
In summary, Microsoft recommends that you follow these guidelines when writing audio drivers for Windows platforms:
Use WDM to realize the benefits of the architecture, including software mixing, wavetable synthesis, and digital routing of the CD audio data.
If your device uses USB audio, use the existing operating system support. No additional minidrivers are needed to make USB audio function in Windows.
For more information on WDM, INF files, and Plug and Play, download the Windows DDKs from
http://www.microsoft.com/ddk/ .
Test the configuration to ensure that you meet WHQL requirements on both Windows 98/Me and Windows 2000/Windows XP.
Finally, submit your devices to WHQL for validation testing.