SetDmaEngineState routine

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:

Syntax


PSET_DMA_ENGINE_STATE SetDmaEngineState;

NTSTATUS SetDmaEngineState(
  _In_ PVOID                context,
  _In_ HDAUDIO_STREAM_STATE streamState,
  _In_ ULONG                numberOfHandles,
  _In_ PHANDLE              handles
)
{ ... }

Parameters

context [in]

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

streamState [in]

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.

numberOfHandles [in]

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

handles [in]

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 codeDescription
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

Target platform

Desktop

Header

Hdaudio.h (include Hdaudio.h)

IRQL

<=DISPATCH_LEVEL

See also

HDAUDIO_BUS_INTERFACE
HDAUDIO_BUS_INTERFACE_V2
HDAUDIO_BUS_INTERFACE_BDL
AllocateDmaBuffer
SetupDmaEngineWithBdl
IMiniportWaveCyclicStream::SetState

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft