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

AllocateContiguousDmaBuffer ルーチンは、物理メモリの 1 つの連続したブロックで構成される DMA バッファーを割り当てます。

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

構文

PALLOCATE_CONTIGUOUS_DMA_BUFFER PallocateContiguousDmaBuffer;

NTSTATUS PallocateContiguousDmaBuffer(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
        ULONG RequestedBufferSize,
  [out] PVOID *DataBuffer,
  [out] PHDAUDIO_BUFFER_DESCRIPTOR *BdlBuffer
)
{...}

パラメーター

[in] _context

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

[in] Handle

DMA エンジンの識別を処理します。 このハンドル値は、AllocateCaptureDmaEngine または AllocateRenderDmaEngine 以前の呼び出しから取得されました。

RequestedBufferSize

要求されたバッファー サイズをバイト単位で指定します。

[out] DataBuffer

データ バッファーを取得します。 このパラメーターは、ルーチンがデータ バッファーのシステム仮想アドレスを書き込む呼び出し元によって割り当てられた PVOID 変数を指します。

[out] BdlBuffer

バッファー記述子リスト (BDL) を取得します。 このパラメーターは、呼び出し元によって割り当てられた PVOID 変数を指します。この変数は、ルーチンが BDL のシステム仮想アドレスを書き込みます。 BDL 割り当てサイズは 1 つのメモリ ページであり、BDL はページ境界で開始されます。

戻り値

呼び出しが成功した場合、AllocateContiguousDmaBuffer はSTATUS_SUCCESSを返します。 それ以外の場合、ルーチンは適切なエラー コードを返します。 次の表に、考えられる戻り状態コードの一部を示します。

備考

AllocateContiguousDmaBuffer ルーチンは、SetupDmaEngineWithBdl および FreeContiguousDmaBuffer ルーチン と組み合わせて使用されます。 これらの 3 つのルーチンは、HD オーディオ DDI のHDAUDIO_BUS_INTERFACE_BDL バージョンでのみ使用できます。 この DDI には、AllocateDmaBuffer および FreeDmaBuffer ルーチンは含まれません。これは、AllocateContiguousDmaBuffer、SetupDmaEngineWithBdl、および FreeContiguousDmaBuffer と組み合わせて使用されることはありません。 SetupDmaEngineWithBdlとは異なり、以前に割り当てられた DMA バッファーを使用するように DMA エンジンを構成 AllocateDmaBuffer、DMA バッファーを割り当て、バッファーを使用するように DMA エンジンを構成します。 詳細については、「2 つの DDI バージョンの違い」を参照してください。

AllocateContiguousDmaBuffer は、指定した DMA エンジンにデータ バッファーを割り当てます。 また、BDL にメモリのページを割り当てます。 ホスト プロセッサ アーキテクチャによっては、一般的なページ サイズは 4,096 バイトまたは 8,192 バイトです。 データ バッファーは、1 つの連続した物理メモリ ブロックで構成されます。

ハンドル パラメーターは、データ バッファーと BDL を使用する DMA エンジンを指定します。 このルーチンは、DMA エンジンのサイズ、配置、位置の要件を満たすストレージを割り当てます。

ルーチンがデータ バッファーと BDL に割り当てるストレージは初期化されていません。 関数ドライバーは、SetupDmaEngineWithBdl ルーチンに送信する前に、BDL を入力する必要があります。 関数ドライバーは、データ転送を管理し、ストリーム識別子を認識するコーデックをプログラミングする役割も担います。

正確な間隔で IOC 割り込みを生成するには、関数ドライバーがデータ バッファーの割り当てを特定のサイズの複数のフラグメントに分割する必要がある場合があります。 各フラグメントは、BDL エントリによって記述されます。 フラグメント サイズを調整して割り込み速度を調整できます。 Intel High Definition Audio Specification (Intel HD Audio web サイト を参照) によると、各フラグメントは 128 バイトの境界で開始する必要がありますが、そのようなアラインメント要件はフラグメントの長さに適用されません。 したがって、1 つのフラグメントの終わりと次のフラグメントの先頭の間にギャップが存在する可能性があります。 SetupDmaEngineWithBdl 呼び出すとき、関数ドライバーは、BDL エントリが記述する個々のフラグメントのサイズの合計を表す bufferSize パラメーターの値を指定する必要があります。 このサイズは、AllocateContiguousDmaBuffer ルーチンの requestedBufferSize パラメーターで指定されたバイト数以下になります。

DMA エンジン ハンドルの有効期間中に、AllocateContiguousDmaBuffer を連続して呼び出して、新しい DMA バッファーを割り当てることができます。 ただし、AllocateContiguousDmaBufferを呼び出す前に、FreeContiguousDmaBuffer 呼び出すことによって、以前に割り当てられた DMA バッファーを解放する必要があります。

AllocateContiguousDmaBuffer、SetupDmaEngineWithBdl、および FreeContiguousDmaBuffer 呼び出し中、DMA エンジンはリセット ストリーム状態である必要があります。 DMA エンジンは、AllocateXxxDmaEngine の呼び出しの直後にリセット状態になります。 DMA エンジンを実行状態に変更するには、SetDmaEngineState 呼び出します。

このルーチンは失敗し、次のいずれかの状況でSTATUS_INVALID_DEVICE_REQUESTエラー コードを返します。

• 以前に割り当てられた DMA バッファーが解放されていません (FreeContiguousDmaBuffer 呼び出すことによって)。
• ストリームがリセット以外の状態です。

必要条件

関連項目

AllocateCaptureDmaEngine の

AllocateDmaBuffer

AllocateRenderDmaEngine の

FreeContiguousDmaBuffer の

FreeDmaBuffer

HDAUDIO_BUS_INTERFACE_BDL

SetDmaEngineState

SetupDmaEngineWithBdl の