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

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

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

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

構文

PALLOCATE_DMA_BUFFER_WITH_NOTIFICATION PallocateDmaBufferWithNotification;

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

パラメーター

[in] _context

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

[in] Handle

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

[in] NotificationCount

オーディオバッファーを介した DMA の進行に基づいて、必要な通知の数を指定します。現在、値 1 または 2 がサポートされています。値が 1 の場合、サイクリックオーディオバッファーが完了するたびに登録された通知イベントが通知され、DMA が先頭に折り返されます。値が 2 の場合、DMA がオーディオバッファーの中間点と末尾 (またはラップアラウンドポイント) を通過すると、登録された通知イベントが通知されます。

[in] RequestedBufferSize

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

[out] BufferMdl

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

[out] AllocatedBufferSize

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

OffsetFromFirstPage

[out] StreamId

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

[out] FifoSize

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

戻り値

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

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

注釈

この AllocateDmaBufferWithNotification ルーチンは、 FreeDmaBufferWithNotification ルーチンと共に使用されます。これら 2 つのルーチンは、HD Audio DDI のHDAUDIO_BUS_INTERFACE_V2 バージョンでのみ使用できます。以前に割り当てられた DMA バッファーを使用するように DMA エンジンを構成する SetupDmaEngineWithBdl とは異なり、DMA バッファーを割り当て、 AllocateDmaBufferWithNotification バッファーを使用するように DMA エンジンも構成します。

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

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

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

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

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

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

Windows Vista 以降のバージョンの Windows では、WaveRT ミニポートドライバーは、 KSPROPERTY_RTAUDIO_BUFFER_WITH_NOTIFICATION プロパティ要求を受信すると、このルーチンを呼び出します。

要件

要件	値
サポートされている最小のクライアント	Windows Vista 以降のバージョンの Windows で使用できます。
対象プラットフォーム	デスクトップ
Header	hdaudio.h (Hdaudio.h を含む)
IRQL	PASSIVE_LEVEL。