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

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

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 個の記述子が含まれている場合は、0 から n-1 の番号が付けられます。 lvi 値は少なくとも 1 である必要があります。つまり、DMA エンジンが操作を開始するには、少なくとも 2 つの有効なエントリが BDL に含まれている必要があります。

[in] Isr

呼び出し元の ISR への関数ポインター。呼び出し元が BDL 内の 1 つ以上のバッファー記述子に割り込みオンコンプリート (IOC) ビットを設定した場合、HD Audio バスドライバーは、ストリームで 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 Audio 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 エンジンを割り当てる必要があります。 handle パラメーターは、前の 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 Audio コントローラーは 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 を割り当てる必要があります。