typedef struct _WAVE_INFO {
ULONG Key;
#define WAVE_INFO_KEY (*(ULONG *)"Wave")
PDEVICE_OBJECT DeviceObject;
SOUND_DMA_BUFFER DMABuf;
SOUND_DOUBLE_BUFFER DoubleBuffer;
SOUND_BUFFER_QUEUE BufferQueue;
ULONG SamplesPerSec;
UCHAR BitsPerSample;
UCHAR Channels;
BOOLEAN FormatChanged;
PWAVEFORMATEX WaveFormat;
BOOLEAN LowPrioritySaved;
PFILE_OBJECT LowPriorityHandle;
PLOCAL_DEVICE_INFO LowPriorityDevice;
struct {
SOUND_BUFFER_QUEUE BufferQueue;
ULONG SamplesPerSec;
UCHAR BitsPerSample;
UCHAR Channels;
PWAVEFORMATEX WaveFormat;
ULONG State;
} LowPriorityModeSave;
PVOID MRB[2];
KEVENT DmaSetupEvent;
KEVENT DpcEvent;
KEVENT TimerDpcEvent;
KSPIN_LOCK DeviceSpinLock;
#if DBG
BOOLEAN LockHeld;
#endif
PKINTERRUPT Interrupt;
BOOLEAN Direction;
UCHAR DMAType;
UCHAR InterruptHalf;
volatile BOOLEAN DMABusy;
volatile BOOLEAN DpcQueued;
ULONG Overrun;
PVOID HwContext;
WORK_QUEUE_ITEM WaveStopWorkItem;
KEVENT WaveReallyComplete;
PSOUND_QUERY_FORMAT_ROUTINE QueryFormat;
PWAVE_INTERFACE_ROUTINE
HwSetupDMA,
HwStopDMA,
HwSetWaveFormat;
KDPC TimerDpc;
KTIMER DeviceCheckTimer;
BOOLEAN GotWaveDpc;
BOOLEAN DeviceBad;
BOOLEAN TimerActive;
UCHAR FailureCount;
} WAVE_INFO, *PWAVE_INFO;
The WAVE_INFO structure contains wave device context information.
Members
Key
Internal only, for debugging. Should be "Wave".
DeviceObject
Pointer to a DEVICE_OBJECT structure.
DMABuf
Structure describing a DMA buffer. Structure type is SOUND_DMA_BUFFER. Call SoundGetCommonBuffer to fill in this structure.
DoubleBuffer
Internal only. This is an internal structure containing additional information about the DMA buffer. The structure contains a pointer to the buffer described by the DMABuf member. The structure type is SOUND_DOUBLE_BUFFER.
BufferQueue
Internal only. For queuing device requests.
SamplesPerSec
Current samples per second.
BitsPerSample
Current bits per sample, per channel.
Channels
Current number of channels.
FormatChanged
Format has changed. Tested by HwSetWaveFormat function.
WaveFormat
Format for non-PCM formats.
LowPrioritySaved
LowPriorityHandle
LowPriorityDevice
LowPriorityModeSave
These four members are used by soundlib.lib for management of low priority mode, which allows a wave input device to nominate itself as pre-emptible if its dispatch routine receives IOCTL_WAVE_SET_LOW_PRIORITY. Only one user can be in low priority mode at a time.
MRB
Internal only. Contains adapter information.
DmaSetupEvent
Internal only. Stores event to wait on during channel allocation.
DpcEvent
Internal only. Used for synchronization with DPC termination.
TimerDpcEvent
Internal only. Used to track rogue devices.
DeviceSpinLock
Internal only. Used for DPC synchronization.
LockHeld
Internal only. Used for debugging.
Interrupt
Pointer to an interrupt object. Should be obtained from a call to SoundConnectInterrupt.
Direction
Set by soundlib.lib. Set to TRUE for output, FALSE for input.
DMAType
Type of DMA. One of the following enumerated values:
enum {
SoundNoDMA,
SoundAutoInitDMA, // Use auto-initialize
SoundReprogramOnInterruptDMA, // Reprogram on interrupt
Sound2ChannelDMA // Keep 2 channels going
};
Sound2ChannelDMA is not currently supported in soundlib.lib. It is intended for a device whose hardware uses two DMA channels and alternates between them to achieve continuous sound.
InterruptHalf
Internal only. Reserved for use when the DMAType member's value is SoundReprogramOnInterruptDMA.
DMABusy
Set by soundlib.lib if DMA is in progress.
DpcQueued
Used for detecting an overrun condition. The ISR should test DpcQueued. If clear, the ISR can call IoRequestDpc. If set, an overrun has occurred and the ISR should set Overrun (see below) instead of calling IoRequestDpc.
Overrun
Set by the driver's ISR if overrun occurs.
HwContext
Pointer to a driver-defined structure containing device-specific hardware information. Typically used by functions pointed by the HwSetupDMA, HwStopDMA, and HwSetWaveFormat members.
WaveStopWorkItem
Internal only. Structure used for calls to ExInitializeWorkItem and ExQueueWorkItem, when soundlib.lib is using system worker threads.
WaveReallyComplete
Internal only. Set by system worker thread after HwStopDMA has returned.
QueryFormat
Pointer to a driver-supplied function called when the driver receives IOCTL_WAVE_SET_FORMAT or IOCTL_WAVE_QUERY_FORMAT message. The function type is SOUND_QUERY_FORMAT_ROUTINE.
HwSetupDMA
Pointer to a driver-supplied function that programs the hardware to start a DMA transfer. Function type is WAVE_INTERFACE_ROUTINE.
The function is called after soundlib.lib has set up map registers by calling IoMapTransfer. For more information, see \src\mmedia\soundlib\wave.c.
HwStopDMA
Points to a driver-supplied function that sends commands to the hardware to stop DMA transfers. The function type is WAVE_INTERFACE_ROUTINE.
The function is called just before soundlib.lib calls IoFlushAdapterBuffers. For more information, see \src\mmedia\soundlib\wave.c.
Note: HwStopDMA must not acquire the device exclusion mutex that soundlib.lib uses to synchronize device access. Code in soundlib.lib waits for a transfer to complete before starting a new one, and this wait occurs inside a request to the device, when the mutex is owned by the waiting thread. This means that HwStopDMA can require extra synchronization code, even though no further hardware calls to the current device can occur until the current transfer is complete.
HwSetWaveFormat
Points to a driver-supplied function that sends commands to the hardware to set the wave format. The function type is WAVE_INTERFACE_ROUTINE.
The function is called just before soundlib.lib starts each DMA transfer. For more information, see \src\mmedia\soundlib\wave.c.
TimerDpc
Internal only. Structure used by soundlib.lib for calls to KeInitializeDpc.
DeviceCheckTimer
Internal only. Structure used by soundlib.lib for calls to KeInitializeTimer.
GotWaveDpc
Internal only. Indicates the device is active.
DeviceBad
Internal only. Set if the device doesn't send interrupts.
TimerActive
Internal only. Indicates the device is active.
FailureCount
Internal only. Contains count of failed I/O attempts. If the count reaches 30, BadDevice is set.
Comments
One WAVE_INFO structure must be defined for each waveform device (input or output) that can be in operation simultaneously. WAVE_INFO is defined in wave.h.
Allocate a WAVE_INFO structure from the nonpaged memory pool by calling ExAllocatePool, and then zero it by calling RtlZeroMemory. To initialize a WAVE_INFO structure, assign values to the HwSetupDMA, HwStopDMA, and HwSetWaveFormat members and then call SoundInitializeWaveInfo.
To create a waveform device object, call SoundCreateDevice and specify a WAVE_INFO structure pointer for the DeviceSpecificData parameter.