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

[アーティクル]
02/29/2024

ルーチンは 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) を取得します。このパラメーターは、ルーチンが BDL のシステム仮想アドレスを書き込む呼び出し元によって割り当てられた PVOID 変数を指します。 BDL 割り当てサイズは 1 つのメモリページであり、BDL はページ境界で開始されます。

戻り値

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

リターンコード	説明
STATUS_UNSUCCESSFUL	呼び出し元が高すぎる割り込み要求レベル (IRQL) で実行されていることを示します。
STATUS_INSUFFICIENT_RESOURCES	バッファーの割り当てが失敗したことを示します。
STATUS_INVALID_HANDLE	ハンドルパラメーターの値が無効であることを示します。
STATUS_INVALID_PARAMETER	パラメーター値の 1 つが正しくない (不適切なポインター) ことを示します。
STATUS_DEVICE_NOT_READY	ハードウェアプログラミングがタイムアウトしたことを示します。これが発生した場合、ハードウェアが侵害された状態になっている可能性があります。
STATUS_INVALID_DEVICE_REQUEST	ストリームがリセット状態ではないこと、または DMA エンジンにバッファーが既に割り当てられていることを示します。

注釈

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

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

handle パラメーターは、データバッファーと BDL を使用する DMA エンジンを指定します。ルーチンは、DMA エンジンのサイズ、配置、および位置の要件を満たす記憶域を割り当てます。

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

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

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

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

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