PFREE_DMA_BUFFER callback function (hdaudio.h)

Article
10/21/2021

The FreeDmaBuffer routine frees a DMA buffer that was previously allocated by a call to AllocateDmaBuffer.

The function pointer type for a FreeDmaBuffer routine is defined as follows.

Syntax

PFREE_DMA_BUFFER PfreeDmaBuffer;

NTSTATUS PfreeDmaBuffer(
  [in] PVOID _context,
  [in] HANDLE Handle
)
{...}

Parameters

[in] _context

Specifies the context value from the Context member of the HDAUDIO_BUS_INTERFACE or the HDAUDIO_BUS_INTERFACE_V2 structure.

[in] Handle

Handle identifying the DMA engine. This handle value was obtained from a previous call to AllocateCaptureDmaEngine or AllocateRenderDmaEngine.

Return value

FreeDmaBuffer 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
STATUS_UNSUCCESSFUL	Indicates that the caller is running at an IRQL that is too high.
STATUS_INVALID_HANDLE	Indicates that the handle parameter value is invalid.
STATUS_INVALID_DEVICE_REQUEST	Indicates that the stream is not in the reset state or that no buffer is currently allocated for the DMA engine.

Remarks

The FreeDmaBuffer routine is used in conjunction with the AllocateDmaBuffer routine. These two routines are available only in the HDAUDIO_BUS_INTERFACE version 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.

The routine fails and returns error code STATUS_INVALID_DEVICE_REQUEST in either of the following circumstances:

The client calls FreeDmaBuffer when no buffer is currently allocated for the DMA engine.
The stream is in a state other than reset.

Requirements

Requirement	Value
Target Platform	Desktop
Header	hdaudio.h (include Hdaudio.h)
IRQL	PASSIVE_LEVEL