PALLOCATE_RENDER_DMA_ENGINE コールバック関数 (hdaudio.h)

[アーティクル]
08/07/2023

このルーチンは AllocateRenderDmaEngine 、レンダリングストリームに DMA エンジンを割り当てます。

ルーチンの関数ポインター型 AllocateRenderDmaEngine は、次のように定義されます。

構文

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
)
{...}

パラメーター

[in] _context

HDAUDIO_BUS_INTERFACE、HDAUDIO_BUS_INTERFACE_V2、または HDAUDIO_BUS_INTERFACE_BDL 構造体の Context メンバーのコンテキスト値を指定します。

[in] StreamFormat

要求されたストリーム形式を指定します。このパラメーターは、ストリームのデータ形式を指定する HDAUDIO_STREAM_FORMAT 型の呼び出し元によって割り当てられた構造体を指します。

[in] Stripe

ストライピングを有効にするかどうかを指定します。 TRUE の場合、ルーチンは DMA 転送でストライピングを有効にします。 FALSE の場合、ストライピングは無効になります。

[out] Handle

DMA エンジンへのハンドルを取得します。このパラメーターは、DMA エンジンを識別するハンドルをルーチンが書き込む呼び出し元によって割り当てられた HANDLE 変数を指します。

[out] ConverterFormat

コンバーター形式を取得します。このパラメーターは、ルーチンがエンコードされた形式を書き込む HDAUDIO_CONVERTER_FORMAT 型の呼び出し元によって割り当てられた構造体を指します。

戻り値

AllocateRenderDmaEngine は、呼び出しが DMA エンジンの予約に成功した場合にSTATUS_SUCCESSを返します。それ以外の場合、ルーチンは適切なエラーコードを返します。次の表は、考えられるリターンエラーコードの一部を示しています。

リターンコード	説明
STATUS_BUFFER_TOO_SMALL	DMA エンジンが、要求されたストリーム形式をサポートするのに十分な内部 FIFO ストレージを割り当てることができないことを示します。
STATUS_INSUFFICIENT_RESOURCES	DMA エンジンが使用できないか、要求が使用可能な帯域幅リソースを超えているかどうかを示します。
STATUS_INVALID_PARAMETER	いずれかのパラメーター値が正しくない (無効なパラメーター値または不適切なポインター) ことを示します。

注釈

このルーチンは、レンダリング DMA エンジンを割り当て、ストリームのデータ形式を指定します。成功した場合、ルーチンは、呼び出し元が DMA エンジンを識別するために後で使用するハンドルを出力します。

ルーチンは AllocateRenderDmaEngine ハードウェアリソース (DMA エンジン) を予約しますが、DMA ハードウェアは構成しません。 DMA エンジンを予約するためにこのルーチンを呼び出した後、関数ドライバーは DMA バッファーを DMA エンジンに割り当て、バッファーを使用するようにエンジンを構成する必要があります。

HD Audio DDI のHDAUDIO_BUS_INTERFACE バージョンを使用している場合、関数ドライバーは AllocateDmaBuffer ルーチンを呼び出して、HD オーディオバスドライバーに DMA 転送用のデータバッファーを割り当て、バッファーを使用するように DMA エンジンを設定します。
DDI のHDAUDIO_BUS_INTERFACE_BDL バージョンを使用する場合、関数ドライバーは AllocateContiguousDmaBuffer を呼び出して DMA バッファーを割り当て、 SetupDmaEngineWithBdl ルーチンを呼び出して、バッファーを使用するように DMA エンジンを設定します。

streamFormat パラメーターは、キャプチャストリームのデータ形式を指定します。の呼び出し AllocateRenderDmaEngineに続いて、 ChangeBandwidthAllocation を呼び出すことでストリームの形式を変更できます。

stripe パラメーターは、DMA エンジンがストライピングを使用してデータ転送を高速化するかどうかを指定します。詳細については、「ストライピング」を参照してください。

ルーチンは、handle パラメーターを使用して、AllocateDmaBuffer、ChangeBandwidthAllocation、FreeDmaBuffer、SetupDmaEngineWithBdl、および SetDmaEngineState の後続の呼び出しで割り当てられた DMA エンジンを識別するために呼び出し元が使用するハンドルを出力します。関数ドライバーは、 FreeDmaEngine を呼び出してハンドルを解放します。

converterFormat パラメーターを使用して、ルーチンは、呼び出し元が出力コンバーターのプログラミングに使用できるストリーム記述子値を出力します。このルーチンは、 streamFormat パラメーターの情報を 16 ビット整数にエンコードします。詳細については、「 HDAUDIO_CONVERTER_FORMAT」を参照してください。

への AllocateRenderDmaEngine呼び出しが成功した直後に、DMA エンジンはリセットストリーム状態になります。 SetDmaEngineState を呼び出して DMA エンジンを実行中、一時停止、または停止状態に変更する前に、クライアントは最初にエンジンの DMA バッファーを割り当てる必要があります。

WDM オーディオドライバーは、NewStream メソッドの実行中にピン作成時にを呼び出AllocateRenderDmaEngineします (たとえば、「IMiniportWavePci::NewStream」を参照してください)。