NTSTATUS
SoundGetCommonBuffer(
IN PDEVICE_DESCRIPTION DeviceDescription,
IN OUT PSOUND_DMA_BUFFER SoundAutoData
);
The SoundGetCommonBuffer function allocates a buffer for use by waveform devices during auto-initialize DMA transfers, and maps the buffer so it is accessible to both the processor and the device.
Parameters
DeviceDescription
Pointer to an initialized DEVICE_DESCRIPTION structure. (For a description of this structure, see HalGetAdapter.)
SoundAutoData
Pointer to a SOUND_DMA_BUFFER structure. Generally this is the address of the DMABuf member of a WAVE_INFO structure.
Return Value
Returns one of the following values.
| Value | Definition |
| STATUS_SUCCESS | Operation succeeded. |
| STATUS_DEVICE_CONFIGURATION_ERROR | Couldn’t find adapter. |
| STATUS_INSUFFICIENT_RESOURCES | Not enough memory to allocate buffer. |
Comments
The returned buffer is described by the contents of the SOUND_DMA_BUFFER structure.
SoundGetCommonBuffer calls HalGetAdapter to obtain an adapter object and HalAllocateCommonBuffer to get a buffer. If a buffer of the requested size is not available, a smaller one is returned. The smallest buffer that can be requested is 4 kilobytes.
After the buffer has been allocated, the function calls IoAllocateMdl and MmBuildMdlForNonPagedPool to build a memory descriptor list (MDL). A MDL is needed by soundlib.lib for calls to IoMapTransfer.
If the requested buffer size is large, soundlib.lib might not use the entire buffer. To find out how much of the buffer is actually used, call SoundGetDMABufferSize.
Prior to being unloaded, the driver must free the allocated buffer space by calling SoundFreeCommonBuffer.
Drivers calling SoundGetCommonBuffer must include wave.h.