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

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

このルーチンは AllocateDmaBuffer 、DMA エンジンのシステムメモリにデータバッファーを割り当てます。

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

構文

PALLOCATE_DMA_BUFFER PallocateDmaBuffer;

NTSTATUS PallocateDmaBuffer(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  SIZE_T RequestedBufferSize,
  [out] PMDL *BufferMdl,
  [out] PSIZE_T AllocatedBufferSize,
  [out] PUCHAR StreamId,
  [out] PULONG FifoSize
)
{...}

パラメーター

[in] _context

HDAUDIO_BUS_INTERFACEおよびHDAUDIO_BUS_INTERFACE_V2構造体の Context メンバーからのコンテキスト値を指定します。

[in] Handle

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

[in] RequestedBufferSize

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

[out] BufferMdl

割り当てられたバッファーを含む物理メモリページを取得します。このパラメーターは、呼び出し元によって割り当てられた PMDL 変数を指します。この変数は、バッファーを記述するメモリ記述子リスト (MDL) へのポインターをルーチンが書き込みます。

[out] AllocatedBufferSize

割り当てられたバッファーサイズをバイト単位で取得します。このパラメーターは、ルーチンが割り当てられたバッファーのサイズを書き込む呼び出し元割り当てSIZE_T変数を指します。

[out] StreamId

ストリーム識別子を取得します。このパラメーターは、ルーチンがストリームに割り当てるストリーム識別子を書き込む呼び出し元によって割り当てられた UCHAR 変数を指します。

[out] FifoSize

DMA エンジンの FIFO サイズをバイト単位で取得します。このパラメーターは、ルーチンが FIFO サイズを書き込む呼び出し元割り当て ULONG 変数を指します。

戻り値

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

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

注釈

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

パラメーター requestedBufferSize で要求されたサイズのバッファーを DMA エンジンが使用できない場合、ルーチンは、要求されたサイズにできるだけ近いバッファーを割り当てます。

オーディオまたはモデムコーデックのファンクションドライバーは、データ転送を管理し、ストリーム識別子を認識するためにコーデックをプログラミングする役割を担います。

ルーチンは、バッファーを含む物理メモリページを一覧表示する MDL を出力します。バッファーベースアドレスは、リスト内の最初の物理ページの先頭と一致します。

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

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

FIFO サイズは、DMA エンジンが内部バッファーに保持できる最大バイト数です。ハードウェアの実装に応じて、DMA エンジンの FIFO サイズは静的であるか、ストリーム形式の変更に応じて動的に変化する可能性があります。 FIFO サイズの詳細については、Intel HD Audio Web サイトの Intel High Definition Audio Specification を参照してください。

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

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

Windows Server 2003、Windows XP、Windows 2000、Windows Me/98 では、WDM オーディオドライバーは、 NewStream メソッド (ピン作成時) または SetFormat メソッド (HD オーディオ DDI でXxxDmaEngine の割り当てルーチンのいずれかを呼び出した後) の実行中に、このルーチンを呼び出します。詳細については、「 IMiniportWavePci::NewStream 」および「IMiniportWavePciStream::SetFormat」を参照してください。