ChangeBandwidthAllocation routine

The ChangeBandwidthAllocation routine changes a DMA engine's bandwidth allocation on the HD Audio Link.

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

Syntax


PCHANGE_BANDWIDTH_ALLOCATION ChangeBandwidthAllocation;

NTSTATUS ChangeBandwidthAllocation(
  _In_   PVOID context,
  _In_   HANDLE handle,
  _In_   PHDAUDIO_STREAM_FORMAT streamFormat,
  _Out_  PHDAUDIO_CONVERTER_FORMAT converterFormat
)
{ ... }

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.

handle [in]

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

streamFormat [in]

Specifies the requested stream format. This parameter points to a caller-allocated structure of type HDAUDIO_STREAM_FORMAT that specifies a data format for the stream.

converterFormat [out]

Retrieves the converter format. This parameter points to a caller-allocated structure of type HDAUDIO_CONVERTER_FORMAT into which the routine writes the encoded format. For more information, see the following Remarks section.

Return value

ChangeBandwidthAllocation returns STATUS_SUCCESS if the call succeeds. Otherwise, the routine returns an appropriate error code. The following table shows some of the possible return error 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_PARAMETER

Indicates that one of the parameter values is not correct (bad pointer or invalid stream format).

STATUS_BUFFER_TOO_SMALL

Indicates that the DMA engine is unable to allocate sufficient internal FIFO storage to support the requested stream format.

STATUS_INSUFFICIENT_RESOURCES

Indicates that insufficient bandwidth is available to satisfy the request.

STATUS_INVALID_DEVICE_REQUEST

Indicates that the stream is not in the reset state or that a buffer is still allocated for the DMA engine.

 

Remarks

The caller obtains an initial bandwidth allocation for a DMA engine by calling AllocateCaptureDmaEngine or AllocateRenderDmaEngine. Thereafter, the caller can change the bandwidth allocation by calling ChangeBandwidthAllocation.

Through the converterFormat parameter, the routine outputs a stream descriptor value that the caller can use to program the input or output converters. The routine encodes the information from the streamFormat parameter into a 16-bit integer. For more information, see HDAUDIO_CONVERTER_FORMAT.

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

If the ChangeBandwidthAllocation call fails, the existing bandwidth reservation remains in effect. The bandwidth allocation changes only if the call succeeds.

In Windows Vista and later, a wave miniport driver calls this routine during execution of its SetFormat method (after calling one of the AllocateXxxDmaEngine routines in the HD Audio DDI). For more information, see IMiniportWavePciStream::SetFormat.

Requirements

Header

Hdaudio.h (include Hdaudio.h)

IRQL

PASSIVE_LEVEL

See also

HDAUDIO_BUS_INTERFACE
HDAUDIO_BUS_INTERFACE_V2
HDAUDIO_BUS_INTERFACE_BDL
HDAUDIO_STREAM_FORMAT
HDAUDIO_CONVERTER_FORMAT
AllocateCaptureDmaEngine
AllocateRenderDmaEngine
FreeDmaBuffer
FreeContiguousDmaBuffer
IMiniportWavePciStream::SetFormat

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft