PALLOCATE_CAPTURE_DMA_ENGINE - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
// hdaudio.h
PALLOCATE_CAPTURE_DMA_ENGINE PallocateCaptureDmaEngine;
NTSTATUS PallocateCaptureDmaEngine(
[in] PVOID _context,
[in] UCHAR CodecAddress,
[in] PHDAUDIO_STREAM_FORMAT StreamFormat,
[out] PHANDLE Handle,
[out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}
View the official Windows Driver Kit DDI referenceNo description available.
The AllocateCaptureDmaEngine routine allocates a DMA engine for a capture stream.
The function pointer type for an AllocateCaptureDmaEngine routine is defined as follows.
_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.
CodecAddress [in]Specifies a codec address. This parameter identifies the serial data in (SDI) line on which the codec supplies the capture data to the HD Audio bus controller. A bus controller with n SDI pins can support up to n codecs with addresses ranging from 0 to n-1.
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.
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.
AllocateCaptureDmaEngine returns STATUS_SUCCESS if the call succeeds in reserving a DMA engine. Otherwise, possible return values include the error codes in the following table.
| 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 capture 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 AllocateCaptureDmaEngine 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 AllocateCaptureDmaEngine, the stream's format can be changed by calling ChangeBandwidthAllocation.
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 input 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 AllocateCaptureDmaEngine, 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 Windows Driver Model (WDM) audio driver calls AllocateCaptureDmaEngine at pin-creation time during execution of its NewStream method (for example, see IMiniportWavePci::NewStream).