PALLOCATE_DMA_BUFFER_WITH_NOTIFICATION callback function (hdaudio.h)
The AllocateDmaBufferWithNotification routine allocates a data buffer in system memory for a DMA engine.
The function pointer type for an AllocateDmaBufferWithNotification routine is defined as follows.
Syntax
PALLOCATE_DMA_BUFFER_WITH_NOTIFICATION PallocateDmaBufferWithNotification;
NTSTATUS PallocateDmaBufferWithNotification(
[in] PVOID _context,
[in] HANDLE Handle,
[in] ULONG NotificationCount,
[in] SIZE_T RequestedBufferSize,
[out] PMDL *BufferMdl,
[out] PSIZE_T AllocatedBufferSize,
PSIZE_T OffsetFromFirstPage,
[out] PUCHAR StreamId,
[out] PULONG FifoSize
)
{...}
Parameters
[in] _context
Specifies the context value from the Context member of the HDAUDIO_BUS_INTERFACE_V2 structure.
[in] Handle
A handle that identifies the DMA engine. This handle value was obtained from a previous call to AllocateCaptureDmaEngine or AllocateRenderDmaEngine.
[in] NotificationCount
Specifies the number of notifications that are needed, based on DMA progression through the audio buffer. Currently, a value of 1 or 2 is supported. When the value is 1, any registered notification events are signaled each time the cyclic audio buffer is completed and DMA wraps back to the beginning. When the value is 2, any registered notification events are notified as DMA passes the midpoint of the audio buffer as well as at the end (or the wraparound point).
[in] RequestedBufferSize
Specifies the requested buffer size, in bytes.
[out] BufferMdl
Retrieves the physical memory pages that contain the allocated buffer. This parameter points to a caller-allocated variable that is a pointer to a memory descriptor list (PMDL). This routine writes a pointer that describes the memory descriptor list buffer, to the PMDL variable.
[out] AllocatedBufferSize
Retrieves the allocated buffer size, in bytes. This parameter points to a caller-allocated SIZE_T variable into which the routine writes the size of the allocated buffer.
OffsetFromFirstPage
[out] StreamId
Retrieves the stream identifier. This parameter points to a caller-allocated UCHAR variable into which the routine writes the stream identifier that the routine assigns to the stream.
[out] FifoSize
Retrieves the DMA engine's FIFO size, in bytes. This parameter points to a caller-allocated ULONG variable into which the routine writes the FIFO size.
Return value
The AllocateDmaBufferWithNotification routine returns STATUS_SUCCESS if the call succeeds. Otherwise, the routine returns an appropriate error code. The following table shows some of the possible return error codes.
| Return code | Description |
|---|---|
|
Indicates that the caller is running at an IRQL that is too high. |
|
Indicates that the buffer allocation has failed. |
|
Indicates that the handle parameter value is invalid. |
|
Indicates that one of the parameter values is incorrect (bad pointer). |
|
Indicates that the hardware programming timed out. If this occurs, the hardware might be in a compromised state. |
|
Indicates that the stream is not in the reset state or that a buffer is already allocated for the DMA engine and has not yet been freed. |
Remarks
The AllocateDmaBufferWithNotification routine is used together with the FreeDmaBufferWithNotification routine. These two routines are available only in the HDAUDIO_BUS_INTERFACE_V2 version of the HD Audio DDI. Unlike SetupDmaEngineWithBdl, which configures the DMA engine to use a previously allocated DMA buffer, AllocateDmaBufferWithNotification allocates a DMA buffer and also configures the DMA engine to use the buffer.
If the DMA engine cannot use a buffer of the size that is requested in parameter requestedBufferSize, the routine allocates a buffer that is as close as possible to the requested size.
The function driver for an audio or modem codec is responsible for programming the codec to manage the data transfers and to recognize the stream identifier.
AllocateDmaBufferWithNotification outputs an MDL that lists the physical memory pages that contain the buffer. The buffer base address coincides with the start of the first physical page in the list.
During the lifetime of a DMA engine handle, AllocateDmaBufferWithNotification can be called successively to allocate new DMA buffers. However, before calling AllocateDmaBufferWithNotification, any previously allocated DMA buffer must first be freed by calling FreeDmaBufferWithNotification.
During calls to AllocateDmaBufferWithNotification and FreeDmaBufferWithNotification, the DMA engine must be in the reset stream state. The DMA engine is in the reset stream state immediately following the call to AllocateCaptureDmaEngine or AllocateRenderDmaEngine. To change the DMA engine to the run state, call SetDmaEngineState.
The FIFO size is the maximum number of bytes that the DMA engine can hold in its internal buffer. Depending on the hardware implementation, a DMA engine's FIFO size can either be static or vary dynamically with changes in the stream format. For more information about the FIFO size, see the Intel High Definition Audio Specification.
In Windows Vista and later versions of Windows, a WaveRT miniport driver calls this routine when it receives the KSPROPERTY_RTAUDIO_BUFFER_WITH_NOTIFICATION property request.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available in Windows Vista and later versions of Windows. |
| Target Platform | Desktop |
| Header | hdaudio.h (include Hdaudio.h) |
| IRQL | PASSIVE_LEVEL. |