Edit

Share via

PSET_DMA_ENGINE_STATE callback function (hdaudio.h)

  • Article

The SetDmaEngineState routine sets the state of one or more DMA engines to the Running, Stopped, Paused, or Reset state.

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

Syntax

PSET_DMA_ENGINE_STATE PsetDmaEngineState;

NTSTATUS PsetDmaEngineState(
  [in] PVOID _context,
  [in] HDAUDIO_STREAM_STATE StreamState,
  [in] ULONG NumberOfHandles,
  [in] PHANDLE Handles
)
{...}

Parameters

[in] _context

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

[in] StreamState

Specifies the new stream state. Set this parameter to one of the following HDAUDIO_STREAM_STATE enumeration values:

  • PauseState (paused)
  • ResetState (reset)
  • RunState (running)
  • StopState (stopped)
In the current implementation, PauseState and StopState represent the same hardware state.

[in] NumberOfHandles

Specifies the number of handles in the handles array. Set this parameter to a nonzero value.

[in] Handles

Pointer to an array of handles to DMA engines. Specify a non-NULL value for this parameter.

Return value

SetDmaEngineState returns STATUS_SUCCESS if the call succeeds in changing the DMA engines' states. Otherwise, the routine returns an appropriate error code. The following table shows some of the possible return status codes.

Return code Description
STATUS_INVALID_HANDLE
 Indicates that one of the handles is invalid.
STATUS_INVALID_PARAMETER
 Indicates that one of the parameter values is incorrect (invalid parameter value or bad pointer).
STATUS_INVALID_DEVICE_REQUEST
 Indicates that no buffer is currently allocated for one of the DMA engines.

Remarks

This routine changes the state of one or more DMA engines to the state that the streamState parameter specifies. The routine synchronizes the state transitions of all the DMA engines that the handles in the handles array identify. For more information, see Synchronizing Two or More Streams.

Before calling this routine, set up each DMA engine in the handles array:

  • If using the HDAUDIO_BUS_INTERFACE version of the HD Audio DDI, call AllocateDmaBuffer to set up the DMA engine.
  • If using the HDAUDIO_BUS_INTERFACE_BDL version of the DDI, call SetupDmaEngineWithBdl to set up the DMA engine.
If no DMA buffer is currently allocated for any DMA engine in the handles array, an attempt to change the stream to any state other than Reset causes the SetDmaEngineState call to fail and return error code STATUS_INVALID_DEVICE_REQUEST.

The stream state cannot transition directly between Running and Reset. Instead, the stream must first pass through an intermediate state of Paused or Stopped:

  • From a Running or Reset state, the stream state can change directly to either Paused or Stopped.
  • From a paused or stopped state, the stream state can change directly to either Running or Reset.
A WDM audio driver calls this routine during a call to its SetState method. For example, see IMiniportWaveCyclicStream::SetState.

Requirements

Requirement Value
Target Platform Desktop
Header hdaudio.h (include Hdaudio.h)
IRQL <=DISPATCH_LEVEL

See also

AllocateDmaBuffer

HDAUDIO_BUS_INTERFACE

HDAUDIO_BUS_INTERFACE_BDL

HDAUDIO_BUS_INTERFACE_V2

IMiniportWaveCyclicStream::SetState

SetupDmaEngineWithBdl