ACXのロギングとデバッグ

  • [アーティクル]

このトピックでは、ACX オーディオ クラス拡張機能のログ記録、トレース、デバッグについて説明します。

Note

ACX ヘッダーとライブラリは、WDK 10.0.22621.2428 (2023 年 10 月 24 日リリース) には含まれていませんが、以前のバージョンと WDK の最新 (25000 シリーズ ビルド) Insider Preview で使用できます。 WDK のプレビュー バージョンの詳細については、「Windows Driver Kit (WDK) のプレビュー バージョンのインストール」を参照してください。

ACX ドライバーのログ記録

ドライバーのソフトウェア トレースは、通常、カーネル モードプロセスとユーザー モード プロセスの両方のトレース メッセージをログに記録するカーネル レベルの機能である Windows イベント トレーシング (ETW) に基づいています。 ACX ドライバーは WDF ドライバーであり、すべての WDF ログ機能とイベント機能を ACX ドライバー開発者が利用できます。

WPP

ETW は使い方がやや複雑なため、ほとんどのドライバー開発者は Windows ソフトウェア トレース プリプロセッサ (WPP) を使用します。これにより、ETW トレース用のドライバーをインストルメント化するプロセスが簡略化および強化されます。

ACX は、トレースとデバッグに WPP ログを使用します。 詳しくは、「KMDF ドライバーでの WPP ソフトウェア トレースの使用」と「Windows ドライバーへの WPP ソフトウェア トレースの追加」を参照してください。

インフライト レコーダー (IFR)

インフライト レコーダー (IFR) はサポートされており、WDFKD、RCDRKD、または ACXKD デバッガー拡張機能が使用可能な場合に表示できます。 IFR ログの操作に関する一般的な情報については、「KMDF と UMDF 2 ドライバーでのインフライト トレース レコーダー (IFR) の使用」と「ビデオ: デバッガーなしでドライバーの IFR ログにアクセスする」を参照してください。

ACX は、他の ETW プロバイダーを使用して主要なイベントをログに記録し、これらの特別なイベントの視覚化を簡略化します。

ドライバーへのログ記録の追加

サード パーティのドライバーは、WPP イベントと ETW イベントも使用することを強くお勧めします。

このコード例では、戻り値をチェックし、適切なエラーをログに記録します。


    //
    // The driver uses this DDI to delete the circuits from the current device. 
    //
    status = AcxDeviceRemoveCircuit(Device, devCtx->Speaker);
    if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove speaker circuit, continuing with ReleaseHardware, %!STATUS!", status); }
    status = AcxDeviceRemoveCircuit(Device, devCtx->MicArray);
    if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove micarray circuit, continuing with ReleaseHardware, %!STATUS!", status); }
    status = AcxDeviceRemoveCircuit(Device, devCtx->SpeakerHp);
    if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove speakerHp circuit, continuing with ReleaseHardware, %!STATUS!", status); }
    status = AcxDeviceRemoveCircuit(Device, devCtx->MicrophoneHp);
    if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove microphoneHp circuit, continuing with ReleaseHardware, %!STATUS!", status); }
    status = AcxDeviceRemoveCircuit(Device, devCtx->HDMI);
    if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove HDMI circuit, continuing with ReleaseHardware, %!STATUS!", status); }

トースター ドライバーのサンプル コードのおすすめのバージョンでは、WMI トレースの例と再利用可能なトレース コードが提供されています。 トースター サンプルの詳細については、「トースター サンプル ドライバー」を参照してください。

ACX ドライバー のログ記録の推奨事項

ACX ドライバーの信頼性を向上させるには、ログ記録における次の動作を検討してください。

  • ストリーム バッファー IO またはその他の通常の信号処理アクティビティからの予期しない戻り値。
  • 予期しない電源状態または電源状態の遷移。
  • 更新または再インストール中に行われた呼び出しに関連するエラー。
  • "オーディオなし" につながる可能性があるその他の動作は、ログ記録の対象となり得ます。

WMI トレース デバッガー拡張機能の使用

デバッガーでトレース イベントを表示するには、WMI 拡張機能 (Wmitrace.dll) を使用します。 WMI イベント トレースを制御および表示するように設計された関数のライブラリが含まれています。 詳しくは、「WMI トレース拡張機能 (Wmitrace.dll)」を参照してください。

ACX ドライバーのデバッグ

ACX ドライバーは WDF ドライバーであるため、WDF ドライバーに関して説明したデバッグ技術は、ACX ドライバーにも適用されます。 WDF ドライバーのデバッグについては、次のトピックを参照してください。

デバッグ ツールに関する一般的な情報

Debugging Tools for Windows (WinDbg、KD、CDB、NTSD)

KMDF のデバッグ

ビデオ チュートリアル

ACX カーネル デバッガー拡張機能ライブラリ (AcxKd.dll)

デバッグを支援するために、ACX にはコンパニオン カーネル デバッガー拡張機能ライブラリ (AcxKd.dll) があります。 このライブラリは、開発者が単一およびマルチスタックのオーディオ パスの問題を追跡する場合に役立ちます。 kd 拡張機能を使用すると、開発者は ACX 構造体内を見ることができます。

Note

このデバッガー拡張機能は開発中であり、利用可能になり次第、こちらで情報を提供します。

関連項目

ACX オーディオ クラス拡張機能の概要

ACX オブジェクトの概要