PALLOCATE_DMA_BUFFER callback function (hdaudio.h)
The AllocateDmaBuffer routine allocates a data buffer in system memory for a DMA engine.
The function pointer type for an AllocateDmaBuffer routine is defined as follows.
Syntax
PALLOCATE_DMA_BUFFER PallocateDmaBuffer;
NTSTATUS PallocateDmaBuffer(
[in] PVOID _context,
[in] HANDLE Handle,
[in] SIZE_T RequestedBufferSize,
[out] PMDL *BufferMdl,
[out] PSIZE_T AllocatedBufferSize,
[out] PUCHAR StreamId,
[out] PULONG FifoSize
)
{...}
Parameters
[in] _context
Specifies the context value from the Context members of the HDAUDIO_BUS_INTERFACE and HDAUDIO_BUS_INTERFACE_V2 structures.
[in] Handle
Handle identifying the DMA engine. This handle value was obtained from a previous call to AllocateCaptureDmaEngine or AllocateRenderDmaEngine.
[in] RequestedBufferSize
Specifies the requested buffer size in bytes.
[out] BufferMdl
Retrieves the physical memory pages that contains the allocated buffer. This parameter points to a caller-allocated PMDL variable into which the routine writes a pointer to a memory descriptor list (MDL) that describes the buffer.
[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.
[out] StreamId
Retrieves the stream identifier. This parameter points to a caller-allocated UCHAR variable into which the routine writes the stream identifier that it 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
AllocateDmaBuffer returns STATUS_SUCCESS if the call succeeds. Otherwise, the routine returns an appropriate error code. The following table shows some of the possible return status codes.
| Return code | Description |
|---|---|
|
Indicates that the caller is running at an IRQL that is too high. |
|
Indicates that buffer allocation 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. |
Remarks
The AllocateDmaBuffer routine is used in conjunction with the FreeDmaBuffer routine. These two routines are available only in the HDAUDIO_BUS_INTERFACE and the HDAUDIO_BUS_INTERFACE_V2 versions of the HD Audio DDI. This DDI does not include the AllocateContiguousDmaBuffer, SetupDmaEngineWithBdl, and FreeContiguousDmaBuffer routines, which are never used in conjunction with AllocateDmaBuffer and FreeDmaBuffer. Unlike SetupDmaEngineWithBdl, which configures the DMA engine to use a previously allocated DMA buffer, AllocateDmaBuffer both allocates a DMA buffer and configures the DMA engine to use the buffer.
If the DMA engine cannot use a buffer of the size 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.
The routine 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, AllocateDmaBuffer can be called successively to allocate new DMA buffers. However, before calling AllocateDmaBuffer, any previously allocated DMA buffer must first be freed by calling FreeDmaBuffer.
During calls to AllocateDmaBuffer and FreeDmaBuffer, the DMA engine must be in the reset stream state. The DMA engine is in the reset state immediately following the call to AllocateXxxDmaEngine. 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 at the Intel HD Audio website.
This routine fails and returns error code STATUS_INVALID_DEVICE_REQUEST in either of the following circumstances:
- Any previously allocated DMA buffer has not been freed (by calling FreeDmaBuffer).
- The stream is in a state other than reset.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Desktop |
| Header | hdaudio.h (include Hdaudio.h) |
| IRQL | PASSIVE_LEVEL |