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

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

ルーチンは AllocateCaptureDmaEngine 、キャプチャストリームに対して DMA エンジンを割り当てます。

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

構文

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

パラメーター

[in] _context

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

[in] CodecAddress

コーデックアドレスを指定します。このパラメーターは、コーデックが HD オーディオバスコントローラーにキャプチャデータを提供する (SDI) 行のシリアルデータを識別します。 n 個の SDI ピンを備えたバスコントローラーは、0 ~ n-1 の範囲のアドレスを持つ最大 n 個のコーデックをサポートできます。

[in] StreamFormat

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

[out] Handle

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

[out] ConverterFormat

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

戻り値

AllocateCaptureDmaEngine は、呼び出しが DMA エンジンの予約に成功した場合にSTATUS_SUCCESSを返します。それ以外の場合は、次の表のエラーコードが返されます。

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

注釈

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

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

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

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

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

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

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

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