PALLOCATE_RENDER_DMA_ENGINE callback function (hdaudio.h)

Article
10/21/2021

The AllocateRenderDmaEngine routine allocates a DMA engine for a render stream.

The function pointer type for an AllocateRenderDmaEngine routine is defined as follows.

Syntax

PALLOCATE_RENDER_DMA_ENGINE PallocateRenderDmaEngine;

NTSTATUS PallocateRenderDmaEngine(
  [in]  PVOID _context,
  [in]  PHDAUDIO_STREAM_FORMAT StreamFormat,
  [in]  BOOLEAN Stripe,
  [out] PHANDLE Handle,
  [out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}

Parameters

[in] _context

Specifies the context value from the Context members of the HDAUDIO_BUS_INTERFACE,HDAUDIO_BUS_INTERFACE_V2, or HDAUDIO_BUS_INTERFACE_BDL structures.

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

[in] Stripe

Specifies whether to enable striping. If TRUE, the routine enables striping in the DMA transfers. If FALSE, striping is disabled.

[out] Handle

Retrieves the handle to the DMA engine. This parameter points to a caller-allocated HANDLE variable into which the routine writes a handle that identifies the DMA engine.

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

Return value

AllocateRenderDmaEngine returns STATUS_SUCCESS if the call succeeds in reserving a DMA engine. Otherwise, the routine returns an appropriate error code. The following table shows some of the possible return error codes.

Return code	Description
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 either no DMA engine is available or the request exceeds the available bandwidth resources.
STATUS_INVALID_PARAMETER	Indicates that one of the parameter values is incorrect (invalid parameter value or bad pointer).

Remarks

This routine allocates a render DMA engine and specifies the data format for the stream. If successful, the routine outputs a handle that the caller subsequently uses to identify the DMA engine.

The AllocateRenderDmaEngine routine reserves hardware resources (the DMA engine) but does not configure the DMA hardware. After calling this routine to reserve a DMA engine, a function driver must assign a DMA buffer to the DMA engine and configure the engine to use the buffer:

If using the HDAUDIO_BUS_INTERFACE version of the HD Audio DDI, the function driver calls the AllocateDmaBuffer routine to have the HD Audio bus driver allocate a data buffer for DMA transfers and set up the DMA engine to use the buffer.
If using the HDAUDIO_BUS_INTERFACE_BDL version of the DDI, the function driver calls AllocateContiguousDmaBuffer to allocate the DMA buffer and calls the SetupDmaEngineWithBdl routine to set up the DMA engine to use the buffer.

The streamFormat parameter specifies the data format for the capture stream. Following the call to AllocateRenderDmaEngine, the stream's format can be changed by calling ChangeBandwidthAllocation.

The stripe parameter specifies whether the DMA engine is to use striping to speed up data transfers. For more information, see Striping.

Through the handle parameter, the routine outputs a handle that the caller uses to identify the allocated DMA engine in subsequent calls to AllocateDmaBuffer, ChangeBandwidthAllocation, FreeDmaBuffer, SetupDmaEngineWithBdl, and SetDmaEngineState. The function driver frees the handle by calling FreeDmaEngine.

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

Immediately following a successful call to AllocateRenderDmaEngine, the DMA engine is in the reset stream state. Before calling SetDmaEngineState to change the DMA engine to the running, paused, or stopped state, the client must first allocate a DMA buffer for the engine.

A WDM audio driver calls AllocateRenderDmaEngine at pin-creation time during execution of its NewStream method (for example, see IMiniportWavePci::NewStream).

Requirements

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