PALLOCATE_RENDER_DMA_ENGINE - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
// hdaudio.h
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
)
{...}
View the official Windows Driver Kit DDI referenceNo description available.
The AllocateRenderDmaEngine routine allocates a DMA engine for a render stream.
The function pointer type for an AllocateRenderDmaEngine routine is defined as follows.
_context [in]Specifies the context value from the Context members of the HDAUDIO_BUS_INTERFACE,HDAUDIO_BUS_INTERFACE_V2, or HDAUDIO_BUS_INTERFACE_BDL structures.
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.
Stripe [in]Specifies whether to enable striping. If TRUE, the routine enables striping in the DMA transfers. If FALSE, striping is disabled.
Handle [out]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.
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.
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). |
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:
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).