PFREE_CONTIGUOUS_DMA_BUFFER callback function

The FreeContiguousDmaBuffer routine frees a DMA buffer and buffer descriptor list (BDL) that were allocated by a call to AllocateContiguousDmaBuffer.

The function pointer type for a FreeContiguousDmaBuffer routine is defined as:

Syntax


PFREE_CONTIGUOUS_DMA_BUFFER FreeContiguousDmaBuffer;

NTSTATUS FreeContiguousDmaBuffer(
  _In_ PVOID  context,
  _In_ HANDLE handle
)
{ ... }

Parameters

context [in]

Specifies the context value from the Context member of the HDAUDIO_BUS_INTERFACE_BDL structure.

handle [in]

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

Return value

FreeContiguousDmaBuffer 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 codeDescription
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 FreeContiguousDmaBuffer routine is used in conjunction with the SetupDmaEngineWithBdl and AllocateContiguousDmaBuffer routines. These three routines are available only in the HDAUDIO_BUS_INTERFACE_BDL version of the HD Audio DDI. This DDI does not include the AllocateDmaBuffer and FreeDmaBuffer routines, which are never used in conjunction with AllocateContiguousDmaBuffer, SetupDmaEngineWithBdl, and FreeContiguousDmaBuffer. 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. For more information, see Differences between the Two DDI Versions.

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

  • The client calls FreeContiguousDmaBuffer when no buffer is currently allocated for the DMA engine.

  • The stream is in a state other than reset.

Requirements

Target platform

Desktop

Header

Hdaudio.h (include Hdaudio.h)

IRQL

PASSIVE_LEVEL

See also

HDAUDIO_BUS_INTERFACE_BDL
AllocateCaptureDmaEngine
AllocateRenderDmaEngine
AllocateContiguousDmaBuffer
SetupDmaEngineWithBdl
AllocateDmaBuffer
FreeDmaBuffer

 

 

Send comments about this topic to Microsoft

Show: