PCHANGE_BANDWIDTH_ALLOCATION callback function (hdaudio.h)

Article
10/21/2021

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 follows.

Syntax

PCHANGE_BANDWIDTH_ALLOCATION PchangeBandwidthAllocation;

NTSTATUS PchangeBandwidthAllocation(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  PHDAUDIO_STREAM_FORMAT StreamFormat,
  [out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}

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] Handle

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

[in] StreamFormat

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.

[out] ConverterFormat

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 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_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:

Any previously allocated DMA buffer has not been freed (by calling FreeDmaBuffer or FreeContiguousDmaBuffer).
The stream is in a state other than reset.

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

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