PALLOCATE_CAPTURE_DMA_ENGINE

PALLOCATE_CAPTURE_DMA_ENGINE callback function

The AllocateCaptureDmaEngine routine allocates a DMA engine for a capture stream.

The function pointer type for an AllocateCaptureDmaEngine routine is defined as:

Syntax


PALLOCATE_CAPTURE_DMA_ENGINE AllocateCaptureDmaEngine;

NTSTATUS AllocateCaptureDmaEngine(
  _In_  PVOID                     context,
  _In_  UCHAR                     codecAddress,
  _In_  PHDAUDIO_STREAM_FORMAT    streamFormat,
  _Out_ PHANDLE                   handle,
  _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.

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.

Return value

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

  • 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 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).

Requirements

Target platform

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
AllocateDmaBuffer
AllocateContiguousDmaBuffer
SetupDmaEngineWithBdl
ChangeBandwidthAllocation
SetDmaEngineState
FreeDmaEngine

 

 

Send comments about this topic to Microsoft

Show:
© 2016 Microsoft