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

[アーティクル]
02/07/2025

SetupDmaEngineWithBdl ルーチンは、呼び出し元によって割り当てられた DMA バッファーを使用するように DMA エンジンを設定します。

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

構文

PSETUP_DMA_ENGINE_WITH_BDL PsetupDmaEngineWithBdl;

NTSTATUS PsetupDmaEngineWithBdl(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  ULONG BufferLength,
  [in]  ULONG Lvi,
  [in]  PHDAUDIO_BDL_ISR Isr,
  [in]  PVOID Context,
  [out] PUCHAR StreamId,
  [out] PULONG FifoSize
)
{...}

パラメーター

[in] _context

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

[in] Handle

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

[in] BufferLength

バッファーの長さ。

[in] Lvi

最後に有効なインデックス (LVI) を指定します。このパラメーターには、BDL 内の最後の有効なバッファー記述子のインデックスが含まれています。 DMA エンジンはこの記述子を処理した後、リストの最初の記述子に戻り、処理を続行します。 BDL に n 個の 記述子 含まれている場合は、-1 n0 に番号が付けられます。 lvi 値は少なくとも 1 である必要があります。つまり、DMA エンジンが操作を開始するには、BDL に少なくとも 2 つの有効なエントリが含まれている必要があります。

[in] Isr

呼び出し元の ISR への関数ポインター。呼び出し元が BDL 内の 1 つ以上のバッファー記述子に割り込みオンコンプリート (IOC) ビットを設定した場合、HD オーディオバスドライバーは、ストリームで IOC 割り込みが発生するたびに ISR を呼び出します。このパラメーターは、次の「解説」セクションで定義されている、HDAUDIO_BDL_ISR型の関数ポインターです。

[in] Context

コンテキスト。

[out] StreamId

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

[out] FifoSize

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

戻り値

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

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

備考

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

呼び出し元は、dma バッファーとバッファー内の物理メモリページを記述する BDL の両方のシステムメモリに記憶域を割り当てるために、AllocateContiguousDmaBuffer を呼び出す必要があります。 BDL エントリは、物理的に連続するメモリ内に存在する必要があります。 BDL とバッファーメモリは、Intel High Definition Audio Specification に記載されているアラインメント要件を満たしている必要があります (Intel HD Audio Web サイトを参照)。

BDL と記述するバッファーメモリの両方が、DMA 操作中も有効なままである必要があります。 SetupDmaEngineWithBdlの呼び出しの後、DMA エンジンがバッファーを使用し続ける限り、BDL とバッファーメモリは有効なままである必要があります。 DMA エンジンは、SetupDmaEngineWithBdl をもう一度呼び出してバッファーを置き換えるか、FreeDmaEngine 呼び出して DMA エンジンを解放するまで、バッファーを使用します。関数ドライバーは、FreeContiguousDmaBuffer 呼び出して、必要なくなったバッファーと BDL を解放する役割を担います。

バッファーのメモリを割り当てるときに、呼び出し元は、BDL が指定するメモリの物理的に連続したブロックのアドレス、長さ、および配置に関するすべてのハードウェア制約を満たす必要があります。したがって、SetupDmaEngineWithBdl ルーチンを使用する必要があるのは、バスコントローラーとシステムハードウェアに関する重要な知識を持つクライアントだけです。

DMA エンジンを構成するために SetupDmaEngineWithBdl 呼び出す前に、クライアントは AllocateCaptureDmaEngine 呼び出すか、または AllocateRenderDmaEngine をして DMA エンジンを割り当てる必要があります。ハンドルパラメーターは、XxxDmaEngine を割り当てる前の呼び出しから取得した値です。

呼び出し元は、データ転送を管理し、ストリーム識別子を認識するコーデックをプログラミングする役割を担います。

WDM オーディオドライバーは、NewStream メソッドの実行中に、ピンの作成時にこのルーチンを呼び出します (例: IMiniportWavePci::NewStreamを参照)。

SetupDmaEngineWithBdlの呼び出しの後、DMA エンジンはリセット状態になります。 DMA エンジンを起動するには、SetDmaEngineState 呼び出します。

パラメーター isr は、ストリームで IOC 割り込みが発生するたびに HD Audio バスドライバーが呼び出す ISR を指定します。このパラメーターは、HDAUDIO_BDL_ISR型の関数ポインターであり、次のように定義されています。

typedef void
  (*PHDAUDIO_BDL_ISR)
    (IN VOID *Context, IN ULONG InterruptBitMask);

HD オーディオバスドライバーは、前の SetupDmaEngineWithBdl 呼び出しのコンテキストパラメーターでクライアントが指定したのと同じコンテキスト値で ISR を呼び出します。 interruptBitMask パラメーターには、割り込みの理由を示す HD オーディオコントローラーデバイスのストリームステータスレジスタのビットが含まれています。次の表は、interruptBitMaskの個々のビットの意味を示しています。

ビット番号	意味
31:5	未使用。
4	記述子エラー (DESE)。バッファー記述子のフェッチ中にエラーが発生した場合、HD オーディオコントローラーは DESE ビットを 1 に設定します。
3	FIFO エラー (FIFOE)。 FIFO エラー (出力ストリームでのオーバーランまたは入力ストリームでのアンダーラン) が発生した場合、HD オーディオコントローラーは FIFOE ビットを 1 に設定します。
2	バッファー完了割り込み状態 (BCIS)。バッファー記述子のコマンドバイトで IOC ビットが 1 に設定されている場合、HD オーディオコントローラーは、バッファーの最後のサンプルが処理された後に BCIS ビットを 1 に設定します。
1:0	未使用。

HD オーディオバスドライバーは、未使用のビットを 0 に設定します。 IOC 割り込みが発生したと想定する代わりに、ISR は常に interruptBitMask パラメーターをチェックして、ストリームエラーが発生したかどうかを判断する必要があります。前の表に示した割り込みステータスビットの詳細については、Intel High Definition Audio Specificationのストリームステータスレジスタの説明を参照してください。

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

呼び出し元は、非ページプールからバッファーメモリと BDL を割り当てる必要があります。

必要条件

要件	価値
ターゲットプラットフォームの	デスクトップ
ヘッダー	hdaudio.h (Hdaudio.h を含む)
IRQL	PASSIVE_LEVEL

次の方法で共有

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

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース