PALLOCATE_DMA_BUFFER_WITH_NOTIFICATION callback function (hdaudio.h)

Article
10/21/2021

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
STATUS_UNSUCCESSFUL	Indicates that the caller is running at an IRQL that is too high.
STATUS_INSUFFICIENT_RESOURCES	Indicates that the buffer allocation has failed.
STATUS_INVALID_HANDLE	Indicates that the handle parameter value is invalid.
STATUS_INVALID_PARAMETER	Indicates that one of the parameter values is incorrect (bad pointer).
STATUS_DEVICE_NOT_READY	Indicates that the hardware programming timed out. If this occurs, the hardware might be in a compromised state.
STATUS_INVALID_DEVICE_REQUEST	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.