DOC

A Wave Port Driver for Real-Time Audio Streaming

By Beth Fox,2014-06-22 09:36
11 views 0
A Wave Port Driver for Real-Time Audio Streaming

    A Wave Port Driver for Real-Time Audio Streaming

    Windows Vista Version - September 17, 2007

    Abstract

    This paper provides information about the WaveRT (wave real-time) port driver for the Windows? family of operating systems. It includes guidelines for audio hardware vendors to develop WaveRT miniport drivers for their audio devices. This information applies for the Windows Vista? operating system. What's new in this version. This version of the paper includes the addition of a new (optional) interface that enables the Windows Vista pull-mode (event-driven) audio-streaming technology.

    Future versions of this preview information will be provided in the Windows Driver Kit. If you encounter a conflict between this paper and the Windows Driver Kit, consider the Windows Driver Kit to be factually correct and this paper to be out of date.

    The current version of this paper is maintained on the Web at:

     http://www.microsoft.com/whdc/device/audio/wavertport.mspx

    Contents

    Introduction ....................................................................................................................... 3

    Comparison with WaveCyclic and WavePci ........................................................................ 3

    Stream Latency during Playback ........................................................................................ 6

    Stream Latency during Recording ...................................................................................... 8

    Opening a Real-Time Audio Stream ................................................................................... 9

    Design Guidelines ........................................................................................................... 10

    Hardware Latency ....................................................................................................... 11

    FIFO Interrupts ........................................................................................................... 11

    Scatter-Gather DMA and Buffer Looping ...................................................................... 11

    Position Registers ....................................................................................................... 11

    Clock Register ............................................................................................................ 12

    Register Access .......................................................................................................... 12

    Audio Processing Objects ........................................................................................... 13

    WaveRT Reference ......................................................................................................... 14

    WaveRT Port and Miniport Driver Interfaces ................................................................ 14

    KSPROPSETID_RTAudio Property Set ....................................................................... 34

    Structures ................................................................................................................... 42

    References...................................................................................................................... 49

    A Wave Port Driver for Real-Time Audio Streaming - 2

    Disclaimer:

    This is a preliminary document and may be changed substantially prior to final commercial release of the software described herein.

    The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.

This White Paper is for informational purposes only. MICROSOFT MAKES NO

    WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN

    THIS DOCUMENT.

    Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

    Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

    Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, email address, logo, person, place or event is intended or should be inferred.

? 20032007 Microsoft Corporation. All rights reserved.

    Microsoft, Windows, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

    The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

    Windows Vista Version - September 17, 2007 ? 2003-2007 Microsoft Corporation. All rights reserved.

    A Wave Port Driver for Real-Time Audio Streaming - 3

    Introduction

    This paper provides information about the WaveRT (wave real-time) port driver for the Windows? family of operating systems. This driver provides support for an audio device that has the following capabilities:

    ; Connects to a system bus (for example, PCI).

    ; Can play back or record wave data (audio data that is described by a

    WAVEFORMATEX or WAVEFORMATEXTENSIBLE structure; for information

    about these structures, see the WDK documentation).

    In the next version of the Windows operating system, Windows Vista?, the PortCls system driver provides a WaveRT port driver that achieves real-time performance but uses a simple cyclic buffer for rendering or capturing an audio stream. Like the WaveCyclic and WavePci port drivers in Windows Server? 2003, Windows XP, and earlier, the WaveRT port driver provides the generic system functionality for a kernel-streaming (KS) filter that represents an audio device. The hardware vendor supplies a WaveRT miniport driver to perform the hardware-specific tasks for the filter. For information about PortCls, WaveCyclic, and WavePci, see the Windows Driver Kit (WDK) documentation.

    In Windows Vista and later, the WaveRT port driver is the preferred wave port driver to use with new miniport drivers, although PortCls continues to support WaveCyclic and WavePci miniport drivers. In Windows Server 2003, Windows XP, and earlier, WaveCyclic and WavePci are the only available wave port drivers.

    The WaveRT port driver supports audio applications that reduce the latency of audio streams by using the real-time scheduling support that is available in Windows Vista and later. Hardware innovations, such as the low-latency isochronous transfer modes of PCI Express devices, complement real-time scheduling.

    To take advantage of these improvements, an audio device should be able to play or capture audio data with little or no intervention by the driver software. If designed properly, the audio hardware should require no help from the driver from the time that the audio stream enters the run state until it exits that state. The result is low-latency audio that consumes few host-CPU cycles and is free of timing glitches. The client for the WaveRT port driver is typically the global audio engine. The engine is the operating-system component that mixes the playback streams from the currently running audio applications and writes the mixed stream into the cyclic buffer. The audio device pulls the stream from the buffer and plays it. Comparison with WaveCyclic and WavePci

    In Windows Server 2003, Windows XP, and earlier, the only available wave port drivers are WaveCyclic and WavePci. Audio devices with WaveCyclic and WavePci port drivers require constant attention from the driver to service an audio stream after it enters the run state:

    ; The WaveCyclic port driver requires that a driver thread (a deferred procedure

    call (DPC)) execute at regularly scheduled intervals to perform data copying. ; The WavePci port driver requires the miniport driver to continually acquire and

    release mappings.

    In Windows XP and earlier, most audio devices use WaveCyclic miniport drivers, which are easier to implement correctly than WavePci drivers. However, by Windows Vista Version - September 17, 2007 ? 2003-2007 Microsoft Corporation. All rights reserved.

    A Wave Port Driver for Real-Time Audio Streaming - 4

    requiring data copying, WaveCyclic drivers are sub-optimal for real-time, low-latency audio applications.

    For example, during playback, a WaveCyclic driver thread must copy the client's output data to the cyclic buffer so that the audio device can play it. The thread schedules itself to run in a timing window that is wide enough to contain the CPU cycles that are needed to copy the data. The window must be even wider to absorb unforeseen delays and accommodate timing tolerances in the software-scheduling mechanism. By requiring data copying, the WaveCyclic driver increases the stream latency by the width of the window.

    The WavePci port driver provides better performance than WaveCyclic, but it requires miniport drivers to perform complex operations:

    ; A WavePci miniport driver cannot hold its own spin lock when it calls into the

    port driver to obtain or release mappings. During a call into the port driver, the

    miniport driver must not assume that it has exclusive access to any shared data

    structures that rely on the spin lock to serialize accesses.

    ; A WavePci miniport driver must be able to revoke mappings at any time during

    stream playing. Cancellation of an I/O request packet (IRP) carrying audio data

    causes the port driver to revoke the unprocessed mappings in the IRP.

    Failure to perform these operations correctly leads to synchronization errors and other timing problems. In addition, the WavePci miniport driver must continually obtain and release mappings during the time that the stream is running. Though not as onerous as the data-copying overhead of the WaveCyclic port driver, the software overhead of handling mappings is still a significant drag on performance. The WaveRT port driver combines the simplicity of the WaveCyclic port driver with the performance of the WavePci port driver. It eliminates the handling of mappings and the need for the driver to manipulate the audio data in the stream. Some audio devices have direct memory access (DMA) controllers with idiosyncrasies that limit the kinds of data transfers that they can perform. A DMA engine might typically have any of the following limitations:

    ; Unorthodox buffer alignment requirements.

    ; A 32-bit address range in a 64-bit system.

    ; An inability to handle a contiguous buffer of arbitrary length.

    ; An inability to handle a sample split between two memory pages.

    These limitations place constraints on the size, location, and alignment of hardware buffers. To accommodate the needs of various DMA engines, both the WaveRT and WaveCyclic port drivers give the miniport driver the ability to allocate its own cyclic buffer. However, the WaveRT port driver avoids the performance problems of the WaveCyclic port driver by providing the client with direct access to the buffer, which eliminates the need for data copying.

    To play or record audio, clients of WaveCyclic and WavePci drivers must submit IOCTL_KS_READ_STREAM and IOCTL_KS_WRITE_STREAM requests. By using

    the data-transport facilities in kernel streaming (KS), WaveCyclic and WavePci port drivers experience the following sources of degraded performance:

    ; Transitions between user mode and kernel mode for each I/O request. ; Blocking while waiting for completion of an I/O request.

    ; The CPU cycles necessary to copy the data.

Windows Vista Version - September 17, 2007 ? 2003-2007 Microsoft Corporation. All rights reserved.

    A Wave Port Driver for Real-Time Audio Streaming - 5

    However, the WaveRT port driver does not use the data-transport facilities in KS. Instead, all that a client of the WaveRT port driver must do is set the pin to the run

    state and begin moving audio data directly to or from the cyclic buffer. When some WaveCyclic miniport drivers copy data to or from the cyclic buffer, they also modify the data, which is one way for the driver to work around a design flaw in the audio hardware. For example, Windows assumes that 8-bit pulse coded modulation (PCM) samples are unsigned. If the audio hardware treats 8-bit samples as signed, the driver can intervene by performing the unsigned-to-signed conversion at the same time that it copies the data.

    Such workarounds are more awkward to implement in a WaveRT miniport driver. By increasing the stream latency, they largely defeat the purpose of the WaveRT port driver. Thus, drivers containing such workarounds should not advertise themselves to clients as able to perform real-time audio. The general rule is that a WaveRT miniport driver should never touch the data in the cyclic buffer. Instead, the data should flow directly between the client and the audio hardware without driver intervention, and hardware designers should ensure that such intervention is unnecessary. Flawed hardware that requires the miniport driver to manipulate stream data should use the WaveCyclic port driver instead of the WaveRT port driver.

    Drivers for wave-rendering devices register themselves under the categories KSCATEGORY_AUDIO and KSCATEGORY_RENDER. Similarly, drivers for wave-capture devices register themselves under KSCATEGORY_AUDIO and

    KSCATEGORY_CAPTURE. In addition, a WaveRT driver also registers itself under KSCATEGORY_REALTIME to distinguish itself from WaveCyclic and WavePci drivers, which do not belong to this category. For information about installing device interfaces for an audio adapter, see the WDK documentation.

    Windows Vista Version - September 17, 2007 ? 2003-2007 Microsoft Corporation. All rights reserved.

    A Wave Port Driver for Real-Time Audio Streaming - 6

    Stream Latency during Playback

    Typically, the role of the WaveRT port driver is minimal while an audio playback stream remains in the run state. As shown in the following figure, the client writes audio data to the cyclic buffer, and the audio device reads the data from the buffer and plays it. This activity requires no driver intervention. The audio device is a hardware component, and the client is a software component (typically, the global audio engine).

    Client

    Global Audio

    Engine

    Write to

    BufferStart ofEnd of

    BufferBuffer

    CyclicABBuffer

    PlayWritePositionPosition

    Read from

    BufferAudio Device

    SpeakerFIFODAC

    Position

    Register

Figure 1. Latency of a Playback Stream

    In Figure 1, the write position is the location just past the last sample that the client wrote to the buffer. The play position is the sample that the audio device is currently

    playing. The write and play positions continually progress from left to right as the stream flows through the buffer. When the write or play position reaches the end of the buffer, it wraps around to the start of the buffer.

    The latency from the time that the client writes an audio sample to the buffer until the audio device plays it is simply the separation between the write position and play position. This separation is the sum of the following two sources of latency (marked as A and B in Figure 1):

    ; Latency A: After the audio device reads data from the buffer, the data resides in

    a hardware first in, first out (FIFO) buffer until the audio device clocks the data

    through the digital-to-analog converter (DAC).

    ; Latency B: After the client writes data to the cyclic buffer, the data resides in the

    buffer until the audio device reads the data.

    Windows Vista Version - September 17, 2007 ? 2003-2007 Microsoft Corporation. All rights reserved.

    A Wave Port Driver for Real-Time Audio Streaming - 7

The client has no control over latency A, which depends entirely on the hardware. A

    typical FIFO might store enough samples to feed the DAC for roughly 64 ticks of the sample clock. However, the client does control latency B. Making latency B too

    large introduces unnecessary delays into the system; however, making it too small risks starving the audio device. By scheduling a real-time thread to update the buffer, the client can make the latency smaller than would otherwise be practical. With the real-time scheduling in Microsoft Windows Vista and later, the client thread can schedule itself to run at relatively precise time intervals. By eliminating uncertainty in the times at which the thread executes, the client can reduce the stream latency by removing unnecessary padding from the separation of the write position from the play position.

    To determine how small the separation between the write and play positions can be without risking starvation, the client must consider all of the hardware delays that the data encounters from the time that the client writes the data to the cyclic buffer until the data is played. In addition to the delay through the audio device’s internal FIFO, other hardware delays might exist. For example, packet-based hardware interfaces such as PCI Express introduce transport delays from the time that the CPU initiates a write operation until the data appears in main memory. The client can obtain a summary of these delays by sending a

    KSPROPERTY_RTAUDIO_HWLATENCY property request to the driver.

    After calculating how much separation to maintain between the write and play positions, the client monitors the play position at regular intervals to determine how far to advance the write position. At the start of each interval, the client writes enough data to the cyclic buffer to keep the hardware busy through the start of the next interval.

    One way to obtain the play position is through the

    KSPROPERTY_AUDIO_POSITION property request, but each request requires a transition between user mode and kernel mode. In Windows codenamed

    “Longhorn” and later, PortCls supports the

    KSPROPERTY_RTAUDIO_POSITIONREGISTER property request, which provides

    a more efficient means for obtaining the play position. If the audio hardware contains a position register (shown in Figure 1) that points to the play position, the property request maps the register into a virtual memory address that is accessible to the user-mode client. Thereafter, the client simply reads the current value of the register from this address and no kernel-mode transition is required. For information about KSPROPERTY_AUDIO_POSITION, see the WDK documentation.

    Windows Vista Version - September 17, 2007 ? 2003-2007 Microsoft Corporation. All rights reserved.

    A Wave Port Driver for Real-Time Audio Streaming - 8

    Stream Latency during Recording

    Typically, the role of the WaveRT port driver is minimal while an audio recording stream remains in the run state. As shown in the following figure, the audio device captures audio data and writes it to the cyclic buffer, and then the client reads the data from the buffer. This activity requires no intervention by the driver. The audio device is a hardware component and the client is a software component (typically, the global audio engine).

    Client

    Global Audio

    Engine

    Read fromStart ofEnd ofBufferBufferBuffer

    CyclicBABuffer

    ReadRecord

    PositionPosition

    Audio DeviceWrite to

    BufferADCFIFOMicrophone

    Position

    Register

Figure 2. Latency of a Recording Stream

    Figure 2 identifies the record position as the buffer location of the sample that the

    audio device is currently recording (capturing from the microphone through the analog-to-digital converter, or ADC). Note that the record position is the future

    buffer location into which the audio device will write the sample after it passes through the FIFO. The read position is the next sample that the global audio engine

    will read from the buffer. The record and read positions continually progress from left to right as the stream flows through the buffer. When the record or read position reaches the end of the buffer, it wraps around to the start of the buffer. The latency from the time that the audio device captures an audio sample in the ADC until the client reads it is simply the separation between the record position and read position. This separation is the sum of the following sources of latency (marked as A and B in Figure 2):

    ; Latency A: After capturing data from the ADC, the audio device stores the data

    in a hardware FIFO until it can write the data to the cyclic buffer. Windows Vista Version - September 17, 2007 ? 2003-2007 Microsoft Corporation. All rights reserved.

    A Wave Port Driver for Real-Time Audio Streaming - 9

    ; Latency B: After the audio device writes data to the cyclic buffer, the data

    resides in the buffer until the client reads the data.

The client has no control over latency A, which depends entirely on the hardware. A

    typical FIFO might store roughly 64 samples from the ADC. However, the client does control latency B. Making latency B too large introduces unnecessary delays

    into the system, but making it too small risks reading data too early, before the audio device has written it into the buffer. By scheduling a real-time thread to read the buffer, the client can make the latency smaller than would otherwise be practical. With the real-time scheduling in Windows Vista and later, the client thread can schedule itself to run at relatively precise time intervals. By eliminating uncertainty in the times at which the thread executes, the client can reduce the stream latency by removing unnecessary padding from the separation of the read position from the record position.

    To determine how small the separation between the read and record positions can be made without causing glitches, the client must consider all of the hardware delays that the data encounters from the time that the audio device captures the data until the client reads the data from the cyclic buffer. In addition to the delay through the audio device’s internal FIFO, other hardware delays might exist. The client can obtain a summary of the delays by sending a

    KSPROPERTY_RTAUDIO_HWLATENCY property request to the driver.

    After calculating how much separation to maintain between the record and read positions, the client monitors the record position at regular intervals to determine how much the read position should lag. During each interval, the client reads only the data that the audio device is certain to have already written to the buffer. As described previously, the client can obtain the current record position through either a KSPROPERTY_AUDIO_POSITION or

    KSPROPERTY_RTAUDIO_POSITIONREGISTER property request. The latter is

    more efficient because it allows the client to read the record position directly, without incurring the cost of a kernel-mode transition. For information about KSPROPERTY_AUDIO_POSITION, see the WDK documentation.

    Opening a Real-Time Audio Stream

    During installation, the adapter driver for a real-time audio device registers its WaveRT miniport driver as a device interface under the categories

    KSCATEGORY_AUDIO and KSCATEGORY_REALTIME, as described previously.

    In addition, the driver registers a rendering or capture device under KSCATEGORY_RENDER or KSCATEGORY_CAPTURE, respectively.

    A client, such as the global audio engine, enumerates the KS filters that represent audio devices, selects the real-time audio device, and instantiates it. The resulting filter object has the following components:

    ; An instance of the WaveRT miniport driver to handle all hardware-dependent

    functions for the filter.

    ; An instance of the WaveRT port driver to manage the generic system functions

    for the filter.

    For more information about this process, see the WDK documentation. Windows Vista Version - September 17, 2007 ? 2003-2007 Microsoft Corporation. All rights reserved.

    A Wave Port Driver for Real-Time Audio Streaming - 10

    If the KS filter performs audio rendering, the global audio engine or other client opens a playback stream as follows:

    1. The audio engine opens a pin on the KS filter, and the WaveRT miniport driver

    creates the pin instance. While opening the pin, the audio engine passes the

    stream's wave format to the driver. The driver uses this information to select the

    proper buffer size in the next step.

    2. The audio engine requests a cyclic buffer of a particular size from the WaveRT

    miniport driver, and the driver allocates the buffer (with the

    KSPROPERTY_RTAUDIO_BUFFER property). If the hardware cannot stream

    from a buffer of the requested size, the driver allocates a buffer that comes as

    close as possible to this size while satisfying the hardware constraints and

    system resource limitations. The driver maps the buffer into the hardware's

    DMA engine and also makes the buffer accessible to the audio engine in user

    mode.

    3. The audio engine schedules a real-time thread to periodically write audio data

    to the cyclic buffer.

    4. If the audio hardware does not provide direct support for looped buffers, the

    miniport driver must periodically reprogram the audio hardware.

    The resulting configuration supplies glitch-free audio on audio hardware that either supports looped buffers or uses a real-time thread to regularly update the hardware. The procedure for opening an audio stream for recording is similar. The miniport driver might have to allocate a buffer that is bigger or smaller than the requested size, depending on the hardware restrictions and available system resources. As a rule, the client, which is a software component and is thus much more flexible than the hardware, should accept whatever buffer size the driver allocates. To ensure that the buffer is accessible to the audio hardware, the miniport driver uses the WaveRT port driver’s memory-management methods to allocate the buffer. The

    port driver then maps the allocated buffer into a contiguous block of virtual memory that the user-mode client can access.

    The miniport driver maps the entire allocated buffer into the DMA hardware queue and performs any workarounds that are needed to make the hardware cycle through the buffer (see step 4 in the preceding list). For example, the Intel ICH chipset does not support buffer looping in hardware. Thus, the driver must update a single hardware register periodically, which can be done in either an interrupt service routine (ISR) or a real-time thread. The consumption of processing resources by this operation is modest. For example, on the ICH, the register update should occur about once every 0.5 second on a 48-kHz, stereo, 16-bit stream. Design Guidelines

    This section presents guidelines for writing WaveRT miniport drivers and designing audio hardware that is WaveRT-compatible.

    In addition, Microsoft is developing a set of hardware guidelines for a Universal Audio Architecture (UAA) that incorporates the recommended features of a WaveRT device. The UAA guidelines are based closely on Intel’s High Definition (HD) Audio specification. The WaveRT-friendly features of a UAA-compliant HD Audio device include scatter-gather DMA transfers, at least 32 bits of addressing, and wall clock and position registers that can be mapped to user-mode memory. For a UAA-compliant device, a vendor-supplied custom audio driver is optional unless a custom driver is needed to support a vendor’s proprietary non-

    UAA hardware features, the device can rely entirely on the operating system for Windows Vista Version - September 17, 2007 ? 2003-2007 Microsoft Corporation. All rights reserved.

Report this document

For any questions or suggestions please email
cust-service@docsford.com