Write a UCSI client driver (UCSI クライアントドライバーの作成)

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

USB Type-C Connector System Software Interface (UCSI) ドライバーは、組み込みコントローラー (EC) を搭載した USB Type-C システムのコントローラードライバーとして機能します。

システムが Platform Policy Manager (PPM) を実装しており、UCSI の仕様に記載されているように、以下を介してシステムに接続されている EC 内にある場合:

ACPI トランスポート。ドライバーを作成する必要はありません。 Microsoft 提供のインボックスドライバー (UcmUcsiCx.sys および UcmUcsiAcpiClient.sys) を読み込みます (「UCSI ドライバー」を参照)。
非 ACPI トランスポート (USB、PCI、I2C、UART など) では、コントローラー用のクライアントドライバーを作成する必要があります。

Note

USB Type-C ハードウェアに PD (Power Delivery) ステートマシンを処理する機能がない場合は、USB Type-C ポートコントローラードライバーの作成を検討してください。詳細については、「USB Type-C ポートコントローラードライバーの作成」を参照してください。

Windows 10 バージョン 1809 以降、UCSI の新しいクラス拡張機能 (UcmUcsiCx.sys) が追加され、トランスポートに依存しない方法で UCSI 仕様を実装します。最小限のコードで、UcmUcsiCx へのクライアントであるドライバーが非 ACPI トランスポート経由で USB Type-C ハードウェアと通信できます。このトピックでは、UCSI クラス拡張機能で提供されるサービスと、クライアントドライバーの想定される振る舞いについて説明します。

公式の仕様

適用対象:

Windows 10 Version 1809

WDF のバージョン

KMDF バージョン 1.27

重要な API

UcmUcsiCx クラス拡張機能のリファレンス

サンプル

UcmUcsiCx クライアントドライバーのサンプル

ACPI 部分を必要なバスの実装に置き換えます。

UCSI クラス拡張機能アーキテクチャ

UCSI クラス拡張機能である UcmUcsiCx を使用すると、非 ACPI トランスポートを使用して組み込みコントローラーと通信するドライバーを作成できます。コントローラードライバーは UcmUcsiCx のクライアントドライバーです。 UcmUcsiCx は USB コネクタマネージャー (UCM) のクライアントです。したがって、UcmUcsiCx は独自のポリシーを決定しません。代わりに、UCM によって提供されるポリシーを実装します。 UcmUcsiCx は、クライアントドライバーからの Platform Policy Manager (PPM) の通知を処理するためのステートマシンを実装し、UCM ポリシー決定を実装するコマンドを送信します。これにより、より信頼性の高い問題検出とエラー処理を可能にします。

UCSI クラス拡張アーキテクチャ。

OS Policy Manager (OPM)

OS Policy Manager (OPM) は、UCSI 仕様に記載されているように、PPM とやり取りするロジックを実装します。 OPM では次を担当します。

UCM ポリシーを UCSI コマンドに変換し、UCSI 通知を UCM 通知に変換する。
PPM の初期化、エラーの検出、回復メカニズムに必要な UCSI コマンドを送信する。

UCSI コマンドの処理

一般的な操作には、UCSI 準拠のハードウェアによって実行されるいくつかのコマンドが含まれます。たとえば、GET_CONNECTOR_STATUS コマンドを考えてみましょう。

PPM ファームウェアは、接続変更通知を UcmUcsiCx/クライアントドライバーに送信します。
これに応答して、UcmUcsiCx/クライアントドライバーは GET_CONNECTOR_STATUS コマンドを PPM ファームウェアに返送します。
PPM ファームウェアは GET_CONNECTOR_STATUS を実行し、コマンド完了通知を UcmUcsiCx/client ドライバーに非同期的に送信します。この通知には、実際の接続ステータスに関するデータが含まれています。
UcmUcsiCx/クライアントドライバーはそのステータス情報を処理し、ACK_CC_CI を PPM ファームウェアに送信します。
PPM ファームウェアは ACK_CC_CI を実行し、コマンド完了通知を UcmUcsiCx/クライアントドライバーに非同期的に送信します。
UcmUcsiCx/クライアントドライバーは、GET_CONNECTOR_STATUS コマンドが完了したものと見なします。

Platform Policy Manager (PPM) との通信

UcmUcsiCx は、OPM から PPM ファームウェアへの UCSI コマンドの送信と、PPM ファームウェアからの通知の受信の詳細を抽象化します。 PPM コマンドを WDFREQUEST オブジェクトに変換し、クライアントドライバーに転送します。

PPM 通知

クライアントドライバーは、ファームウェアからの PPM 通知について UcmUcsiCx に通知します。ドライバーは、CCI を含む UCSI データブロックを提供します。 UcmUcsiCx は、通知を OPM や他のコンポーネントに転送し、OPM や他のコンポーネントはそのデータに基づいて適切な処理を行います。
クライアントドライバーへの IOCTL

UcmUcsiCx は、PPM ファームウェアに送信する UCSI コマンドを (IOCTL 要求を通じて) クライアントドライバーに送信します。ドライバーは、UCSI コマンドをファームウェアに送信した後、この要求を完了する必要があります。

電力遷移の処理

クライアントドライバーは電力ポリシーの所有者です。

S0-Idle が原因でクライアントドライバーが Dx 状態になる場合、UcmUcsiCx が UCSI コマンドを含む IOCTL をクライアントドライバーの電源管理キューに送信すると、WDF はドライバーを D0 にします。 S0-Idle のクライアントドライバーは、ファームウェアから PPM 通知があると、再び電源が入った状態に戻る必要があります。なぜなら、S0-Idle では PPM 通知がまだ有効であるためです。

開始する前に

ハードウェアまたはファームウェアが PD ステートマシンを実装しているかどうか、また、トランスポートに応じて、作成する必要があるドライバーのタイプを決定します。

詳細については、「USB Type-C コネクタ用の Windows ドライバーの開発」を参照してください。
Windows 10 デスクトップエディション (Home、Pro、Enterprise、Education) をインストールします。
最新の Windows Driver Kit (WDK) を開発用コンピューターにインストールします。このキットには、クライアントドライバーを作成するために必要なヘッダーファイルとライブラリが含まれています。具体的には、以下が必要になります。
- スタブライブラリ (UcmUcsiCxStub.lib)。このライブラリは、クライアントドライバーによって行われた呼び出しを変換し、クラス拡張機能に渡します。
- ヘッダーファイル Ucmucsicx.h。
- クライアントドライバーはカーネルモードで実行され、KMDF 1.27 ライブラリにバインドされます。
Windows Driver Foundation (WDF) についてよく理解します。推奨資料: Windows Driver Foundation を使用したドライバーの開発 Guy Smith および Penny Orwick 共著

1. クライアントドライバーを UcmUcsiCx に登録する

EVT_WDF_DRIVER_DEVICE_ADD 実装内。

プラグアンドプレイおよび電源管理イベントコールバック関数 (WdfDeviceInitSetPnpPowerEventCallbacks) を設定した後、UcmUcsiDeviceInitInitialize を呼び出して WDFDEVICE_INIT 不透明構造体を初期化します。この呼び出しにより、クライアントドライバーがフレームワークに関連付けられます。
フレームワークデバイスオブジェクト (WDFDEVICE) を作成した後、UcmUcsiDeviceInitialize を呼び出してクライアントドライバーを UcmUcsiCx に登録します。

2. UcmUcsiCx を使用して PPM オブジェクトを作成する

EVT_WDF_DEVICE_PREPARE_HARDWAREの実装では、未加工のリソースと翻訳されたリソースの一覧を受け取った後、リソースを使用してハードウェアを準備します。たとえば、トランスポートが I2C の場合は、ハードウェアリソースを読み取って通信チャンネルを開きます。次に、PPM オブジェクトを作成します。オブジェクトを作成するために、特定の構成オプションを設定する必要があります。

デバイス上のコネクタコレクションへのハンドルを指定します。

UcmUcsiConnectorCollectionCreate を呼び出して、コネクタコレクションを作成します。

デバイス上のコネクタを列挙し、UcmUcsiConnectorCollectionAddConnector を呼び出してコレクションに追加します。

// Create the connector collection.

UCMUCSI_CONNECTOR_COLLECTION* ConnectorCollectionHandle;

status = UcmUcsiConnectorCollectionCreate(Device, //WDFDevice
         WDF_NO_OBJECT_ATTRIBUTES,
         ConnectorCollectionHandle);

// Enumerate the connectors on the device.
// ConnectorId of 0 is reserved for the parent device.
// In this example, we assume the parent has no children connectors.

UCMUCSI_CONNECTOR_INFO_INIT(&connectorInfo);
connectorInfo.ConnectorId = 0;

status = UcmUcsiConnectorCollectionAddConnector ( &ConnectorCollectionHandle,
             &connectorInfo);

デバイスコントローラーを有効にするかどうかを決定します。
PPM オブジェクトを構成して作成します。
1. 手順 1 で作成したコネクタハンドルを指定して、UCMUCSI_PPM_CONFIG 構造体を初期化します。
2. UsbDeviceControllerEnabled メンバーを、手順 2 で決定したブール値に設定します。
3. WDF_OBJECT_ATTRIBUTES でイベントコールバックを設定します。
4. 構成されているすべての構造体を渡して UcmUcsiPpmCreate を呼び出します。
```
UCMUCSIPPM ppmObject = WDF_NO_HANDLE;
PUCMUCSI_PPM_CONFIG UcsiPpmConfig;
WDF_OBJECT_ATTRIBUTES attrib;

UCMUCSI_PPM_CONFIG_INIT(UcsiPpmConfig, ConnectorCollectionHandle);

UcsiPpmConfig->UsbDeviceControllerEnabled = TRUE;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attrib, Ppm);
attrib->EvtDestroyCallback = &EvtObjectContextDestroy;

status = UcmUcsiPpmCreate(wdfDevice, UcsiPpmConfig, &attrib, &ppmObject);
```

3. IO キューを設定する

UcmUcsiCx は、PPM ファームウェアに送信する UCSI コマンドをクライアントドライバーに送信します。これらのコマンドは次の IOCTL 要求の形式で WDF キューに送信されます。

クライアントドライバーは、UcmUcsiPpmSetUcsiCommandRequestQueue を呼び出して、そのキューを作成し、UcmUcsiCx に登録する必要があります。キューは電源管理に対応している必要があります。

UcmUcsiCx により、WDF キュー内に未処理の要求が同時に複数存在することはありません。クライアントドライバーは、UCSI コマンドをファームウェアに送信した後、WDF 要求を完了する必要もあります。

通常、ドライバーは EVT_WDF_DEVICE_PREPARE_HARDWARE の実装内でキューを設定します。

WDFQUEUE UcsiCommandRequestQueue = WDF_NO_HANDLE;
WDF_OBJECT_ATTRIBUTES attrib;
WDF_IO_QUEUE_CONFIG queueConfig;

WDF_OBJECT_ATTRIBUTES_INIT(&attrib);
attrib.ParentObject = GetObjectHandle();

// In this example, even though the driver creates a sequential queue,
// UcmUcsiCx guarantees that will not send another request
// until the previous one has been completed.


WDF_IO_QUEUE_CONFIG_INIT(&queueConfig, WdfIoQueueDispatchSequential);

// The queue must be power-managed.

queueConfig.PowerManaged = WdfTrue;
queueConfig.EvtIoDeviceControl = EvtIoDeviceControl;

status = WdfIoQueueCreate(device, &queueConfig, &attrib, &UcsiCommandRequestQueue);

UcmUcsiPpmSetUcsiCommandRequestQueue(ppmObject, UcsiCommandRequestQueue);

また、クライアントドライバーは UcmUcsiPpmStart を呼び出して、IOCTL 要求を受信する準備ができていることを UcmUcsiCx に通知する必要もあります。 UcmUcsiPpmSetUcsiCommandRequestQueue を通じて UCSI コマンドを受信するための WDFQUEUE ハンドルを作成した後に、EVT_WDF_DEVICE_PREPARE_HARDWARE 内でこの呼び出しを行うことをお勧めします。逆に、ドライバーがこれ以上要求を処理しないようにする場合は、UcmUcsiPpmStop を呼び出す必要があります。この呼び出しは EVT_WDF_DEVICE_RELEASE_HARDWARE 実装内で行います。

4. IOCTL 要求を処理する

USB Type-C パートナーがコネクタに接続されているときに発生する一連のイベントの例を考えてみましょう。

PPM ファームウェアは接続イベントを判断し、クライアントドライバーに通知を送信します。
クライアントドライバーは UcmUcsiPpmNotification を呼び出して、その通知を UcmUcsiCx に送信します。
UcmUcsiCx は OPM ステートマシンに通知し、Get Connector Status コマンドを UcmUcsiCx に送信します。
UcmUcsiCx は要求を作成し、IOCTL_UCMUCSI_PPM_SEND_UCSI_DATA_BLOCK をクライアントドライバーに送信します。
クライアントドライバーはその要求を処理し、コマンドを PPM ファームウェアに送信します。ドライバーはこの要求を非同期で完了し、別の通知を UcmUcsiCx に送信します。
コマンド完了通知が成功すると、OPM ステートマシンはペイロード (コネクタステータス情報を含む) を読み取り、UCM に Type-C 接続イベントを通知します。

この例では、ペイロードは、ファームウェアとポートパートナー間の電力ネゴシエーションステータスの変更が成功したことも示しています。 OPM ステートマシンは別の UCSI コマンドとして Get PDOs を送信します。 Get Connector Status コマンドと同様に、Get PDOs コマンドが正常に完了すると、OPM ステートマシンはこのイベントを UCM に通知します。

EVT_WDF_IO_QUEUE_IO_DEVICE_CONTROL のクライアントドライバーのハンドラーはこのコード例に似ています。要求の処理については、「要求ハンドラー」を参照してください。

void EvtIoDeviceControl(
    _In_ WDFREQUEST Request,
    _In_ ULONG IoControlCode
    )
{
...
    switch (IoControlCode)
    {
    case IOCTL_UCMUCSI_PPM_SEND_UCSI_DATA_BLOCK:
        EvtSendData(Request);
        break;

    case IOCTL_UCMUCSI_PPM_GET_UCSI_DATA_BLOCK:
        EvtReceiveData(Request);
        break;

    default:
        status = STATUS_NOT_SUPPORTED;
        goto Exit;
    }

    status = STATUS_SUCCESS;

Exit:

    if (!NT_SUCCESS(status))
    {
        WdfRequestComplete(Request, status);
    }

}

VOID EvtSendData(
    WDFREQUEST Request
    )
{
    NTSTATUS status;
    PUCMUCSI_PPM_SEND_UCSI_DATA_BLOCK_IN_PARAMS inParams;

    status = WdfRequestRetrieveInputBuffer(Request, sizeof(*inParams),
        reinterpret_cast<PVOID*>(&inParams), nullptr);
    if (!NT_SUCCESS(status))
    {
        goto Exit;
    }

    // Build a UCSI command request and send to the PPM firmware.

Exit:
    WdfRequestComplete(Request, status);
}

VOID EvtReceiveData(
    WDFREQUEST Request
    )
{

    NTSTATUS status;

    PUCMUCSI_PPM_GET_UCSI_DATA_BLOCK_IN_PARAMS inParams;
    PUCMUCSI_PPM_GET_UCSI_DATA_BLOCK_OUT_PARAMS outParams;

    status = WdfRequestRetrieveInputBuffer(Request, sizeof(*inParams),
        reinterpret_cast<PVOID*>(&inParams), nullptr);
    if (!NT_SUCCESS(status))
    {
        goto Exit;
    }

    status = WdfRequestRetrieveOutputBuffer(Request, sizeof(*outParams),
        reinterpret_cast<PVOID*>(&outParams), nullptr);
    if (!NT_SUCCESS(status))
    {
        goto Exit;
    }

    // Receive data from the PPM firmware.
    if (!NT_SUCCESS(status))
    {
        goto Exit;
    }
    WdfRequestSetInformation(Request, sizeof(*outParams));

Exit:
    WdfRequestComplete(Request, status);
}

次の方法で共有

Write a UCSI client driver (UCSI クライアントドライバーの作成)

公式の仕様

WDF のバージョン

重要な API

サンプル

UCSI クラス拡張機能アーキテクチャ

OS Policy Manager (OPM)

UCSI コマンドの処理

Platform Policy Manager (PPM) との通信

電力遷移の処理

開始する前に

1. クライアントドライバーを UcmUcsiCx に登録する

2. UcmUcsiCx を使用して PPM オブジェクトを作成する

3. IO キューを設定する

4. IOCTL 要求を処理する

フィードバック

フィードバック

その他のリソース

次の方法で共有

Write a UCSI client driver (UCSI クライアント ドライバーの作成)

公式の仕様

WDF のバージョン

重要な API

サンプル

UCSI クラス拡張機能アーキテクチャ

OS Policy Manager (OPM)

UCSI コマンドの処理

Platform Policy Manager (PPM) との通信

電力遷移の処理

開始する前に

1. クライアント ドライバーを UcmUcsiCx に登録する

2. UcmUcsiCx を使用して PPM オブジェクトを作成する

3. IO キューを設定する

4. IOCTL 要求を処理する

フィードバック

フィードバック

その他のリソース

Write a UCSI client driver (UCSI クライアントドライバーの作成)

1. クライアントドライバーを UcmUcsiCx に登録する