複合ドライバーに対する機能中断の実装方法

[アーティクル]
04/12/2024

この記事では、ユニバーサルシリアルバス (USB) 3.0 多機能デバイス (複合デバイス) の機能中断と機能リモートウェイクアップ機能の概要について説明します。この記事では、複合デバイスを制御するドライバーにこれらの機能を実装する方法について説明します。この記事は、Usbccgp.sys を置き換える複合ドライバーに適用されます。

ユニバーサルシリアルバス (USB) 3.0 仕様では、機能中断と呼ばれる新機能が定義されています。この機能により、複合デバイスの個々の機能が、他の機能とは無関係に低電力状態に入ります。キーボード用の機能とマウス用の別の機能を定義する複合デバイスについて考えてみましょう。ユーザーはキーボード機能を動作状態に保ちますが、一定期間マウスを移動しません。マウスのクライアントドライバーは、キーボード機能が動作状態にある間に、機能のアイドル状態を検出し、その機能を中断状態に送信できます。

デバイス内の機能の電源状態に関係なく、デバイス全体が中断状態に移行できます。特定の機能とデバイス全体が中断状態になると、デバイスが中断状態にある間、およびデバイスの中断開始プロセスおよび中断終了プロセス全体を通じて、機能の中断状態が保持されます。

USB 2.0 デバイスのリモートウェイクアップ機能 (USB デバイスのリモートウェイクアップを参照) と同様に、USB 3.0 複合デバイスの個々の機能は、他の機能の電源状態に影響を与えずに低電力状態から復帰できます。この機能は、機能リモートウェイクアップと呼ばれます。この機能は、デバイスのファームウェアにリモートウェイクアップビットを設定するプロトコル要求を送信することにより、ホストによって明示的に有効になります。このプロセスは、リモートウェイクアップ用の機能のアーミングと呼ばれます。リモートウェイク関連ビットの詳細については、公式 USB 仕様の図 9-6 を参照してください。

機能がリモートウェイクアップ用に武装している場合、ユーザーイベントが物理デバイスで発生したときにウェイクアップ再開信号を生成するのに十分な電力が機能 (中断状態の場合) に保持されます。その再開信号の結果として、クライアントドライバーは関連付けられている機能の中断状態を終了できます。複合デバイスのマウス機能の例では、ユーザーがアイドル状態のマウスを小刻みに動かすと、マウス機能はホストに再開信号を送信します。ホスト上では、USB ドライバースタックがどの機能が起動したかを検出し、対応する機能のクライアントドライバーに通知を伝達します。その後、クライアントドライバーは機能をウェイクアップし、動作状態に入ることができます。

クライアントドライバーの場合、機能を中断状態に送信し、その機能をウェイクアップする手順は、デバイス全体を中断状態に送信する単機能デバイスドライバーと同様です。次の手順は、これらの手順を要約したものです。

関連する機能がアイドル状態にあることを検出します。
アイドル状態の I/O 要求パケット (IRP) を送信します。
待機ウェイク I/O 要求パケット (IRP) を送信して、リモートウェイクアップの機能を準備する要求を送信します。
Dx パワー IRP (D2 または D3) を送信して、機能を低電力状態に移行します。

上記の手順の詳細については、USB 選択的中断の「USB アイドル要求 IRP の送信」を参照してください。複合ドライバーは、複合デバイス内の機能ごとに物理デバイスオブジェクト (PDO) を作成し、クライアントドライバー (機能デバイススタックの FDO) によって送信された電力要求を処理します。クライアントドライバーがその機能の中断状態を正常に開始および終了するには、複合ドライバーが機能の中断とリモートウェイクアップ機能をサポートし、受信した電力要求を処理する必要があります。

Windows 8 では、USB 3.0 デバイス用の USB ドライバースタックでこれらの機能がサポートされています。さらに、Windows の既定の複合ドライバーである、マイクロソフトが提供する USB 汎用親ドライバー (Usbccgp.sys) に、機能の中断と機能のリモートウェイクアップの実装が追加されました。カスタム複合ドライバーを作成する場合、ドライバーは、次の手順に従って、機能の中断とリモートウェイクアップ要求に関連する要求を処理する必要があります。

手順 1: USB ドライバースタックで機能の中断がサポートされているかどうかを確認する

複合ドライバーの開始デバイスルーチン (IRP_MN_START_DEVICE) で、次の手順を実行します。

USBD_QueryUsbCapability ルーチンを呼び出して、基になる USB ドライバースタックが機能の中断機能をサポートしているかどうかを判断します。この呼び出しには、USBD_CreateHandle ルーチンへの以前の呼び出しで取得した有効な USBD ハンドルが必要です。

USBD_QueryUsbCapability の呼び出しに成功すると、基になる USB ドライバースタックで機能の中断がサポートされているかどうかを判断します。この呼び出しでは、USB ドライバースタックが機能の中断をサポートしていないか、接続されているデバイスが USB 3.0 多機能デバイスではないことを示すエラーコードが返される場合があります。

USBD_QueryUsbCapability 呼び出しで機能の中断がサポートされていることが示されている場合は、複合デバイスを基になる USB ドライバースタックに登録します。複合デバイスを登録するには、IOCTL_INTERNAL_USB_REGISTER_COMPOSITE_DEVICE I/O 制御要求を送信する必要があります。この要求の詳細については、「複合デバイスの登録方法」を参照してください。

登録要求では、REGISTER_COMPOSITE_DEVICE 構造体を使用して、複合ドライバーに関する情報を指定します。 CapabilityFunctionSuspend を 1 に設定していることを確認して、複合ドライバーが機能の中断をサポートしていることを示します。

USB ドライバースタックが機能の中断をサポートしているかどうかを確認する方法を示すコード例については、USBD_QueryUsbCapability を参照してください。

手順 2: アイドル状態の IRP を処理する

クライアントドライバーは、アイドル状態の IRP を送信できます (IOCTL_INTERNAL_USB_SUBMIT_IDLE_NOTIFICATION を参照)。要求は、クライアントドライバーが機能のアイドル状態を検出した後に送信されます。 IRP には、クライアントドライバーによって実装されるコールバック完了ルーチン (アイドルコールバックと呼ばれます) へのポインターが含まれています。アイドルコールバック内では、クライアントは、中断状態に機能を送信する直前に、保留中の I/O 転送の取り消しなどのタスクを実行します。

Note

アイドル状態の IRP メカニズムは、USB 3.0 デバイスのクライアントドライバーでは省略可能です。ただし、ほとんどのクライアントドライバーは、USB 2.0 デバイスと USB 3.0 デバイスの両方をサポートするように作成されています。 USB 2.0 デバイスをサポートするには、複合ドライバーはその IRP に依存して各機能の電源状態を追跡するため、ドライバーはアイドル状態の IRP を送信する必要があります。すべての機能がアイドル状態の場合、複合ドライバーはデバイス全体を中断状態に送ります。

クライアントドライバーからアイドル状態の IRP を受信すると、複合ドライバーは、クライアントドライバーが状態を中断する機能を送信する可能性があることをクライアントドライバーに通知するアイドルコールバックをすぐに呼び出す必要があります。

手順 3: リモートウェイクアップ通知の要求を送信する

クライアントドライバーは、IRP_MN_WAIT_WAKE (待機ウェイク IRP) に設定されたマイナー機能コードを持つ IRP_MJ_POWER IRP を送信することによって、リモートウェイクアップの機能を準備ムする要求を送信できます。クライアントドライバーは、ドライバーがユーザーイベントの結果として動作状態を入力する場合にのみ、この要求を送信します。

待機ウェイク IRP を受信すると、複合ドライバーは USB ドライバースタックに IOCTL_INTERNAL_USB_REQUEST_REMOTE_WAKE_NOTIFICATION I/O 制御要求を送信する必要があります。要求により、USB ドライバースタックは、スタックが再開信号に関する通知を受信したときに、複合ドライバーに通知します。 IOCTL_INTERNAL_USB_REQUEST_REMOTE_WAKE_NOTIFICATION では、REQUEST_REMOTE_WAKE_NOTIFICATION 構造体を使用して要求パラメーターを指定します。複合ドライバーで指定する必要がある値の 1 つは、リモートウェイクアップ用に武装している機能の機能ハンドルです。複合ドライバーは、USB ドライバースタックに複合デバイスを登録する前の要求でそのハンドルを取得します。複合ドライバー登録要求の詳細については、「複合デバイスの登録方法」を参照してください。

要求の IRP では、複合ドライバーは、複合ドライバーによって実装される (リモートウェイクアップ) 完了ルーチンへのポインターを提供します。

次のコード例は、リモートウェイクアップ要求を送信する方法を示しています。

/*++

Description:
    This routine sends a IOCTL_INTERNAL_USB_REQUEST_REMOTE_WAKE_NOTIFICATION request
    to the USB driver stack. The IOCTL is completed by the USB driver stack
    when the function wakes up from sleep.

    Parameters:
    parentFdoExt: The device context associated with the FDO for the
    composite driver.

    functionPdoExt: The device context associated with the PDO (created by
    the composite driver) for the client driver.
--*/

VOID
SendRequestForRemoteWakeNotification(
    __inout PPARENT_FDO_EXT parentFdoExt,
    __inout PFUNCTION_PDO_EXT functionPdoExt
)

{
    PIRP                                irp;
    REQUEST_REMOTE_WAKE_NOTIFICATION    remoteWake;
    PIO_STACK_LOCATION                  nextStack;
    NTSTATUS                            status;

    // Allocate an IRP
    irp =  IoAllocateIrp(parentFdoExt->topDevObj->StackSize, FALSE);

    if (irp)
    {

        //Initialize the USBDEVICE_REMOTE_WAKE_NOTIFICATION structure
        remoteWake.Version = 0;
        remoteWake.Size = sizeof(REQUEST_REMOTE_WAKE_NOTIFICATION);
        remoteWake.UsbdFunctionHandle = functionPdoExt->functionHandle;
        remoteWake.Interface = functionPdoExt->baseInterfaceNumber;

        nextStack = IoGetNextIrpStackLocation(irp);

        nextStack->MajorFunction = IRP_MJ_INTERNAL_DEVICE_CONTROL;
        nextStack->Parameters.DeviceIoControl.IoControlCode = IOCTL_INTERNAL_USB_REQUEST_REMOTE_WAKE_NOTIFICATION;

        nextStack->Parameters.Others.Argument1 = &remoteWake;

        // Caller's completion routine will free the IRP when it completes.

        SetCompletionRoutine(functionPdoExt->debugLog,
                             parentFdoExt->fdo,
                             irp,
                             CompletionRemoteWakeNotication,
                             (PVOID)functionPdoExt,
                             TRUE, TRUE, TRUE);

        // Pass the IRP
        IoCallDriver(parentFdoExt->topDevObj, irp);

    }

    return;
}

IOCTL_INTERNAL_USB_REQUEST_REMOTE_WAKE_NOTIFICATION 要求は、再開信号に関する通知を受け取ったときに、ウェイクアッププロセス中に USB ドライバースタックによって完了します。その間、USB ドライバースタックはリモートウェイクアップ完了ルーチンも呼び出します。

複合ドライバーは、待機ウェイク IRP の保留中を維持し、後で処理するためにキューに配置する必要があります。複合ドライバーは、ドライバーのリモートウェイクアップ完了ルーチンが USB ドライバースタックによって呼び出されたときに、その IRP を完了する必要があります。

手順 4: リモートウェイクアップ用の機能をアームする要求を送信する

この機能を低電力状態に送信するために、クライアントドライバーは、Windows ドライバーモデル (WDM) デバイスの電源状態を D2 または D3 に変更する要求を含む IRP_MN_SET_POWER IRP を送信します。通常、クライアントドライバーは、ドライバーがリモートウェイクアップを要求する待機ウェイク IRP を送信した場合、D2 IRP を送信します。それ以外の場合、クライアントドライバーは D3 IRP を送信します。

D2 IRP を受信すると、複合ドライバーは、最初に待機ウェイク IRP がクライアントドライバーによって送信された以前の要求から保留中かどうかを判断する必要があります。その IRP が保留中の場合、複合ドライバーは、リモートウェイクアップの機能を準備する必要があります。これを行うには、複合ドライバーは SET_FEATURE 制御要求を機能の最初のインターフェイスに送信し、デバイスが再開信号を送信できるようにする必要があります。制御要求を送信するには、USBD_UrbAllocate ルーチンを呼び出して URB 構造体を割り当て、UsbBuildFeatureRequest マクロを呼び出して、SET_FEATURE 要求の URB を書式設定します。呼び出しでは、オペレーションコードとして URB_FUNCTION_SET_FEATURE_TO_INTERFACE を指定し、機能セレクターとして USB_FEATURE_FUNCTION_SUSPEND を指定します。 Index パラメーターで、最上位バイトのビット 1 を設定します。この値は、転送のセットアップパケットの wIndex フィールドにコピーされます。

次の例は、SET_FEATURE 制御要求を送信する方法を示しています。

/*++

Routine Description:

Sends a SET_FEATURE for REMOTE_WAKEUP to the device using a standard control request.

Parameters:
parentFdoExt: The device context associated with the FDO for the
composite driver.

functionPdoExt: The device context associated with the PDO (created by
the composite driver) for the client driver.

Returns:

NTSTATUS code.

--*/
VOID
    NTSTATUS SendSetFeatureControlRequestToSuspend(
    __inout PPARENT_FDO_EXT parentFdoExt,
    __inout PFUNCTION_PDO_EXT functionPdoExt,
    )

{
    PURB                            urb
    PIRP                            irp;
    PIO_STACK_LOCATION              nextStack;
    NTSTATUS                        status;

    status = USBD_UrbAllocate(parentFdoExt->usbdHandle, &urb);

    if (!NT_SUCCESS(status))
    {
        //USBD_UrbAllocate failed.
        goto Exit;
    }

    //Format the URB structure.
    UsbBuildFeatureRequest (
        urb,
        URB_FUNCTION_SET_FEATURE_TO_INTERFACE, // Operation code
        USB_FEATURE_FUNCTION_SUSPEND,          // feature selector
        functionPdoExt->firstInterface,           // first interface of the function
        NULL);

    irp =  IoAllocateIrp(parentFdoExt->topDevObj->StackSize, FALSE);

    if (!irp)
    {
        // IoAllocateIrp failed.
        status = STATUS_INSUFFICIENT_RESOURCES;

        goto Exit;
    }

    nextStack = IoGetNextIrpStackLocation(irp);

    nextStack->MajorFunction = IRP_MJ_INTERNAL_DEVICE_CONTROL;

    nextStack->Parameters.DeviceIoControl.IoControlCode = IOCTL_INTERNAL_USB_SUBMIT_URB;

    //  Attach the URB to the IRP.
    USBD_AssignUrbToIoStackLocation(nextStack, (PURB)urb);

    // Caller's completion routine will free the IRP when it completes.
    SetCompletionRoutine(functionPdoExt->debugLog,
        parentFdoExt->fdo,
        irp,
        CompletionForSuspendControlRequest,
        (PVOID)functionPdoExt,
        TRUE, TRUE, TRUE);


    // Pass the IRP
    IoCallDriver(parentFdoExt->topDevObj, irp);


Exit:
    if (urb)
    {
        USBD_UrbFree( parentFdoExt->usbdHandle, urb);
    }

    return status;

}

複合ドライバーは、USB ドライバースタックに D2 IRP を送信します。他のすべての機能が中断状態にある場合、USB ドライバースタックはコントローラー上の特定のポートレジスタを操作してポートを中断します。

解説

マウス機能の例では、リモートウェイクアップ機能が有効になっているため (ステップ 4 を参照)、ユーザーがマウスを小刻みに動かすと、マウス機能はホストコントローラーへの上流のワイヤ上に再開信号を生成します。次に、コントローラーは、起動した機能に関する情報を含む通知パケットを送信することにより、USB ドライバースタックに通知します。機能起動通知の詳細については、USB 3.0 仕様の図 8-17 を参照してください。

通知パケットを受信すると、USB ドライバースタックは保留中の IOCTL_INTERNAL_USB_REQUEST_REMOTE_WAKE_NOTIFICATION 要求を完了し (手順 3 を参照)、要求で指定され、複合ドライバーによって実装された (リモートウェイクアップ) 完了コールバックルーチンを呼び出します。通知が複合ドライバーに到達すると、クライアントドライバーが以前に送信した wait-wake IRP が完了することにより、機能が動作状態に入ったことを、対応するクライアントドライバーに通知します。

(リモートウェイクアップ) 完了ルーチンでは、複合ドライバーは、保留中のウェイク待機 IRP を完了する作業項目をキューに配置する必要があります。 USB 3.0 デバイスの場合、複合ドライバーは再開信号を送信する機能のみをウェイクアップし、他の機能は中断状態のままにします。作業項目をキューに入れることで、USB 2.0 デバイスの機能ドライバーの既存の実装との互換性が確保されます。作業項目のキューの詳細については、「IoQueueWorkItem」を参照してください。

ワーカースレッドは、待機ウェイク IRP を完了し、クライアントドライバーの完了ルーチンを呼び出します。その後、完了ルーチンは D0 IRP を送信し、機能が動作状態に入ります。待機ウェイク IRP を完了する前に、複合ドライバーは PoSetSystemWake を呼び出して、待機ウェイク IRP を中断状態からシステムをウェイクアップする原因になったものとしてマークする必要があります。電源マネージャーは、システムをウェイクアップしたデバイスに関する情報を含む Windows イベントトレーシング (ETW) イベント (グローバルシステムチャネルで表示可能) をログに記録します。

次の方法で共有

複合ドライバーに対する機能中断の実装方法

手順 1: USB ドライバースタックで機能の中断がサポートされているかどうかを確認する

手順 2: アイドル状態の IRP を処理する

手順 3: リモートウェイクアップ通知の要求を送信する

手順 4: リモートウェイクアップ用の機能をアームする要求を送信する

解説

フィードバック

その他のリソース

次の方法で共有

複合ドライバーに対する機能中断の実装方法

手順 1: USB ドライバー スタックで機能の中断がサポートされているかどうかを確認する

手順 2: アイドル状態の IRP を処理する

手順 3: リモート ウェイクアップ通知の要求を送信する

手順 4: リモート ウェイクアップ用の機能をアームする要求を送信する

解説

関連トピック

フィードバック

その他のリソース

手順 1: USB ドライバースタックで機能の中断がサポートされているかどうかを確認する

手順 3: リモートウェイクアップ通知の要求を送信する

手順 4: リモートウェイクアップ用の機能をアームする要求を送信する