オーディオモジュール通信の実装

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

オーディオモジュールは、比較的アトミックな関数を実行する個別のオーディオ処理ロジックです。オーディオモジュールは、オーディオドライバーまたはオーディオ DSP に配置できます。オーディオモジュールの例としては、DSP ベースのオーディオ処理があります。

Windows 10 リリース 1703 以降では、ユニバーサル Windows プラットフォーム (UWP) アプリとカーネルモードデバイスドライバーからの通信をサポートする API と DDI の両方があります。

このトピックでは、カーネルデバイスドライバーでのオーディオモジュール通信の実装について説明します。

UWP アプリを使用してオーディオデバイスモジュールからコマンドを送信し、変更通知を受信する方法については、「オーディオデバイスモジュールの構成とクエリ」をご覧ください。

オーディオモジュールを使用する理由

OEM は通常、システムに構成アプリケーションをバンドルします。これにより、お客様はこのオーディオシステムの側面を制御し、ユーザーの好みに合わせて調整できます。オーディオサブシステムには、オンホストオーディオ処理オブジェクト、ハードウェア DSP 処理、(すべてオーディオコーデック自体に加えて) スマートアンプなどの特殊なハードウェアなどのさまざまなコンポーネントを含めることができます。ほとんどの場合、これらのコンポーネントは異なるベンダーによって作成および販売されます。これまで、IHV は、互いに統合し、個々のコンポーネント間で情報を送信するための独自のプライベート API を作成してきました。既存の WIN32 構成アプリケーションでは、これらのプライベート API が利用されます。

ユニバーサル Windows プラットフォーム (UWP) には、1 つのアプリケーションをさまざまなデバイスで実行できる一連の API が用意されています。 UWP には、Windows 10 で実行されているアプリケーションに関するお客様の期待に応える新しいルックアンドフィールも導入されました。多くの OEM は、UWP でオーディオ構成アプリケーションを構築したいと考えています。ただし、UWP の主要なセキュリティ機能 (AppContainer サンドボックス) により、アプリケーションからオーディオサブシステム内の他のコンポーネントへの通信ができなくなります。これにより、構成アプリにより以前使用されていたプライベート API が UWP でアクセスできなくなります。

Windows 10 リリース 1703 以降、オーディオモジュール UWP API を使用すると、構成アプリケーションおよびユーザーモードコンポーネントが、新しい KS プロパティセットを通じて検出可能なカーネルおよびハードウェアレイヤー内のモジュールと通信できるようになります。オーディオ IHV と ISV は、Windows によって提供される明確に定義されたインターフェイスを使って、ハードウェアモジュールと通信できるアプリケーションとサービスを記述できます。オーディオモジュール API について詳しくは、「Windows.Media.Devices 名前空間」をご覧ください。

オーディオモジュールの定義

これらの定義は、オーディオモジュールに固有です。

任期	定義
オーディオモジュール	比較的アトミックな関数を実行する個別のオーディオ処理ロジック。オーディオドライバーまたはオーディオ DSP に存在する可能性があります。オーディオモジュールの例として、オーディオ処理オブジェクト (APO) があります。

一般的なオーディオ定義

これらの定義は通常、オーディオドライバーを操作するときに使用されます。

任期	定義
HSA	ハードウェアサポートアプリケーション
UWP	ユニバーサル Windows プラットフォーム
AP	オーディオ処理オブジェクト
DSP	デジタル信号処理

任期	定義
OEM	Original Equipment Manufacturer (相手先ブランド供給)
IHV	独立系ハードウェアベンダー
ISV	独立系ソフトウェアベンダー

Architecture

オーディオモジュールは、ユーザーモードとカーネルモードのオーディオコンポーネントの間でメッセージを送信するための、Windows OS でサポートされるメカニズムを配置します。重要な違いは、オーディオモジュールがトランスポートパイプラインを標準化している点です。そのトランスポート経由で通信プロトコルを確立するのではなく、プロトコルを定義するために ISV と IHV に依存しています。その目的は、既存のサードパーティ製の設計を、わずかな変更だけでオーディオモジュールに簡単に移行できるようにすることです。

この図は、Audio Module API を介してユーザーアプリケーションからオーディオドライバーにオーディオデータがどのように流れるかを示しています。

オーディオモジュールトランスポートが、さまざまなインターフェイスと処理レイヤーを介してユーザーアプリケーションからどのように流れるかを示す図。

デバイスモジュールとストリームモジュールは、クライアントプロセスからアクセスするか、AudioDG から APO に提供されるストリームモジュールインターフェイスを使用して AudioDG で実行されている APO からアクセスするかに応じて存在します。オーディオエンジンとオーディオデバイスグラフ (AudioDG) の一般的な情報については、「Windows オーディオアーキテクチャ」を参照してください。

ドライバーは、 IoReportTargetDeviceChangeAsynchronous 関数を介してモジュールの変更を Windows.Media.Devices に通知します。この関数はモジュール API からクライアントプロセスまたは APO へのコールバックに変換されます。

オーディオモジュール API は、KS wave フィルターと初期化された KS ピン (ストリーム) の 2 つの異なるターゲットメソッドを介してモジュールにアクセスできます。特定のモジュールへの配置とアクセスは、実装に固有です。

HSA や他のアプリケーションは、フィルターハンドルを介して使用可能なモジュールにのみアクセスできます。ストリームに読み込まれる個々の API は、ストリーム対象のオーディオモジュールにアクセスできる唯一のオブジェクトです。 API の詳細については、「Windows オーディオ処理オブジェクト」を参照してください。

コマンドの送信

パラメーターのクエリと変更を行うオーディオモジュールクライアントの手段として、カーネル内のオーディオモジュールとオーディオサブシステムのハードウェアコンポーネントにコマンドを送信できます。オーディオモジュール API のコマンド構造は、疎に定義されており、モジュールを検出して自身を識別する方法が形式化されています。ただし、関連する ISV および IHV によって詳細なコマンド構造を設計および実装し、送信できるメッセージと予想される応答のプロトコルを確立する必要があります。

オーディオモジュールクライアントへのモジュール通知

さらに、オーディオミニポートには、クライアントが特定のモジュールの通知をサブスクライブしている場合に、オーディオモジュールクライアントに通知して情報を渡す方法も用意されています。これらの通知で渡される情報は、オーディオモジュール API によって定義されるのではなく、ISV または IHV によって定義されます。

有効化、無効化、および一般的なトポロジ情報

オーディオモジュール API は、モジュールにコマンドを列挙して送信する方法を定義します。ただし、API は、オーディオモジュールクライアントが特定のモジュールを有効または無効にする方法を明示的に定義しません。さらに、クライアントが相互に関連してトポロジ情報やモジュールの配置を見つける方法は確立されません。 IHV と ISV は、この機能が必要かどうかを判断し、この機能の実装方法を決めることができます。

推奨される方法として、グローバルドライバーモジュールを公開できます。グローバルドライバーモジュールは、これらのトポロジ固有の要求のカスタムコマンドを処理します。

オーディオモジュール DDI

カーネルストリーミングオーディオモジュールのプロパティ

KSPROPSETID_AudioModule によって識別される新しい KS プロパティセットは、オーディオモジュールに固有の 3 つのプロパティに対して定義されています。

PortCls ミニポートドライバーは、ヘルパーインターフェイスが提供されていないため、各プロパティの応答を直接処理する必要があります。

ksmedia.h:

#define STATIC_KSPROPSETID_AudioModule \
    0xc034fdb0, 0xff75, 0x47c8, 0xaa, 0x3c, 0xee, 0x46, 0x71, 0x6b, 0x50, 0xc6
DEFINE_GUIDSTRUCT("C034FDB0-FF75-47C8-AA3C-EE46716B50C6", KSPROPSETID_AudioModule);
#define KSPROPSETID_AudioModule DEFINE_GUIDNAMED(KSPROPSETID_AudioModule)

typedef enum {
    KSPROPERTY_AUDIOMODULE_DESCRIPTORS            = 1,  
    KSPROPERTY_AUDIOMODULE_COMMAND                = 2,
    KSPROPERTY_AUDIOMODULE_NOTIFICATION_DEVICE_ID = 3,
} KSPROPERTY_AUDIOMODULE;

オーディオモジュール記述子

KSPROPERTY_AUDIOMODULE_DESCRIPTORS プロパティのサポートにより、ドライバーがオーディオモジュールに対応していると識別されます。プロパティはフィルターハンドルまたはピンハンドルを通じてクエリを実行でき、KSPROPERTY は DeviceIoControl 呼び出しの入力バッファーとして渡されます。 KSAUDIOMODULE_DESCRIPTOR は、オーディオハードウェア内の各モジュールを記述するように定義されています。これらの記述子の配列は、この要求に応答して返されます

ksmedia.h:

#define AUDIOMODULE_MAX_NAME_SIZE 128

typedef struct _KSAUDIOMODULE_DESCRIPTOR
{
    GUID    ClassId; 
    ULONG   InstanceId;
    ULONG   VersionMajor;
    ULONG   VersionMinor;
    WCHAR   Name[AUDIOMODULE_MAX_NAME_SIZE];
} KSAUDIOMODULE_DESCRIPTOR, *PKSAUDIOMODULE_DESCRIPTOR;

詳しくは、「KSAUDIOMODULE_DESCRIPTOR」をご覧ください。

オーディオモジュールコマンド

KSPROPERTY_AUDIOMODULE_COMMAND プロパティのサポートにより、オーディオモジュールクライアントはカスタムコマンドを送信して、オーディオモジュールでパラメータに対するクエリを実行して、パラメーターを設定できます。プロパティはフィルターハンドルまたはピンハンドルを介して送信でき、KSAUDIOMODULE_PROPERTY は DeviceIoControl 呼び出しの入力バッファーとして渡されます。必要に応じて、クライアントは、カスタムコマンドを送信するために、入力バッファー内の KSAUDIOMODULE_PROPERTY の直後に追加情報を送信できます。

ksmedia.h:

#define AUDIOMODULE_MAX_DATA_SIZE 64000

typedef struct _KSPAUDIOMODULE_PROPERTY
{
    KSPROPERTY Property;
    GUID       ClassId;
    ULONG      InstanceId;
} KSAUDIOMODULE_PROPERTY, *PKSPAUDIOMODULE_PROPERTY;

詳細については、「KSAUDIOMODULE_PROPERTY」を参照してください。

オーディオモジュール通知デバイス ID

信号通知に対してミニポートを有効にして、オーディオモジュールクライアントに情報を渡すには、KSPROPERTY_AUDIOMODULE_NOTIFICATION_DEVICE_ID のサポートが必要です。この ID の有効期間は、Windows オーディオスタックに公開されてアクティブになっているオーディオデバイスの有効期間に関連付けられます。プロパティはフィルターハンドルまたはピンハンドルを介して送信でき、KSPROPERTY は DeviceIoControl 呼び出しの入力バッファーとして渡されます。

詳細については、「KSAUDIOMODULE_PROPERTY」を参照してください。

PortCls ヘルパー - オーディオモジュール通知

ドライバー開発者がオーディオモジュールクライアントに通知を送信できるよう、新しいポートインターフェイスが追加されました。

PortCls.h:

typedef struct _PCNOTIFICATION_BUFFER 
{
    UCHAR NotificationBuffer[1];
} PCNOTIFICATION_BUFFER, *PPCNOTIFICATION_BUFFER;

DECLARE_INTERFACE_(IPortClsNotifications,IUnknown)
{
    DEFINE_ABSTRACT_UNKNOWN()   // For IUnknown

    STDMETHOD_(NTSTATUS, AllocNotificationBuffer)
    (   THIS_
        _In_    POOL_TYPE       PoolType,
        _In_    USHORT          NumberOfBytes,
        _Out_   PPCNOTIFICATION_BUFFER* NotificationBuffer
    )   PURE;
    
    STDMETHOD_(void, FreeNotificationBuffer)
    (   THIS_
        _In_    PPCNOTIFICATION_BUFFER NotificationBuffer
    )   PURE;
    
    STDMETHOD_(void, SendNotificationBuffer)
    (   THIS_
        _In_    const GUID*     NotificationId,
        _In_    PPCNOTIFICATION_BUFFER NotificationBuffer
    )   PURE;
};

//
// Audio module notification definitions.
//
#define STATIC_KSNOTIFICATIONID_AudioModule \
    0x9C2220F0, 0xD9A6, 0x4D5C, 0xA0, 0x36, 0x57, 0x38, 0x57, 0xFD, 0x50, 0xD2
DEFINE_GUIDSTRUCT("9C2220F0-D9A6-4D5C-A036-573857FD50D2", KSNOTIFICATIONID_AudioModule);
#define KSNOTIFICATIONID_AudioModule DEFINE_GUIDNAMED(KSNOTIFICATIONID_AudioModule)

typedef struct _KSAUDIOMODULE_NOTIFICATION {
    union {
        struct {
            GUID        DeviceId;
            GUID        ClassId;
            ULONG       InstanceId;
            ULONG       Reserved;
        } ProviderId;
        LONGLONG        Alignment;
    };
} KSAUDIOMODULE_NOTIFICATION, *PKSAUDIOMODULE_NOTIFICATION;

詳細については、以下を参照してください:

IPortClsNotifications

IPortClsNotifications::AllocNotificationBuffer

IPortClsNotifications::FreeNotificationBuffer

IPortClsNotifications::SendNotificationBuffer

呼び出しシーケンス

ミニポートは、作成し、通知を送信するポートを呼び出します。この図は、一般的な呼び出しシーケンスを示しています。

AudioIPortClsNotifications の呼び出しシーケンスを示す図。

次の方法で共有

オーディオモジュール通信の実装

オーディオモジュールを使用する理由

オーディオモジュールの定義

一般的なオーディオ定義

Architecture

コマンドの送信

オーディオモジュールクライアントへのモジュール通知

有効化、無効化、および一般的なトポロジ情報

オーディオモジュール DDI

ksmedia.h:

オーディオモジュール記述子

ksmedia.h:

オーディオモジュールコマンド

ksmedia.h:

オーディオモジュール通知デバイス ID

PortCls ヘルパー - オーディオモジュール通知

PortCls.h:

呼び出しシーケンス

フィードバック

その他のリソース

次の方法で共有

オーディオ モジュール通信の実装

オーディオ モジュールを使用する理由

オーディオ モジュールの定義

一般的なオーディオ定義

Architecture

コマンドの送信

オーディオ モジュール クライアントへのモジュール通知

有効化、無効化、および一般的なトポロジ情報

オーディオ モジュール DDI

ksmedia.h:

オーディオ モジュール記述子

ksmedia.h:

オーディオ モジュール コマンド

ksmedia.h:

オーディオ モジュール通知デバイス ID

PortCls ヘルパー - オーディオ モジュール通知

PortCls.h:

呼び出しシーケンス

フィードバック

その他のリソース

オーディオモジュール通信の実装

オーディオモジュールを使用する理由

オーディオモジュールの定義

オーディオモジュールクライアントへのモジュール通知

オーディオモジュール DDI

オーディオモジュール記述子

オーディオモジュールコマンド

オーディオモジュール通知デバイス ID

PortCls ヘルパー - オーディオモジュール通知