寫入USB Type-C 連接器驅動程式

發行項
01/18/2024

在這些案例中，您必須撰寫 USB Type-C 連接器驅動程式：

如果您的 USB Type-C 硬體能夠處理電源傳遞 (PD) 狀態電腦。否則，請考慮撰寫USB Type-C埠控制器驅動程式。如需詳細資訊，請參閱寫入USB Type-C埠控制器驅動程式。
如果您的硬體沒有內嵌控制器。否則，請載入 Microsoft 提供的現成驅動程式，UcmUcsi.sys。 (請參閱 ACPI 傳輸的 UCSI 驅動程式) ，或撰寫非 ACPI 傳輸的 UCSI 用戶端驅動程式。

摘要

類別延伸模組和客戶端驅動程式所使用的 UCM 物件
UCM 類別延伸模組所提供的服務
用戶端驅動程式的預期行為

官方規格

適用於

Windows 10

WDF 版本

KMDF 1.15 版
UMDF 2.15 版

重要 API

USB Type-C 連接器驅動程式程式設計參考

描述 USB 連接器管理員 (UCM) 管理 USB Type-C 連接器和連接器驅動程式的預期行為。

UCM 是使用 WDF 類別擴充-用戶端驅動程式模型所設計。類別延伸模組 (UcmCx) 是 Microsoft 提供的 WDF 驅動程式，提供用戶端驅動程式可以呼叫的介面來報告連接器的相關信息。 UCM 用戶端驅動程式會使用連接器的硬體介面，並讓類別延伸模組知道連接器上發生的事件。相反地，類別延伸模組會叫用用戶端驅動程式所實作的回呼函式，以回應操作系統事件。

若要在系統上啟用 USB Type-C 連接器，您必須撰寫用戶端驅動程式。

usb 連接器管理員。

開始之前

在開發電腦上安裝最新的 Windows 驅動程式套件 (WDK) 。套件具有撰寫 UCM 用戶端驅動程式所需的頭檔和連結庫，特別是您需要：
- 存根連結庫， (UcmCxstub.lib) 。連結庫會轉譯客戶端驅動程式所進行的呼叫，並將其傳遞至UcmCx。
- 頭檔 UcmCx.h。
  
  您可以撰寫以使用者模式或核心模式執行的 UCM 用戶端驅動程式。針對使用者模式，它會與UMDF 2.x 連結庫系結;若為核心模式，則為 KMDF 1.15。任一模式的程式設計介面都相同。
決定您的客戶端驅動程式是否支援 USB Type-C 連接器和 USB 電源傳遞的進階功能。

此支援可讓您使用USB Type-C連接器、USB Type-C擴充座和配件，以及USB Type-C電源供應器來建置 Windows 裝置。用戶端驅動程式會報告連接器事件，以允許操作系統在系統中實作USB和耗電量的原則。
在目標計算機上安裝桌面版本的 Windows 10， (家用版、專業版、企業版和教育版) ，或使用USB Type-C 連接器 Windows 10 行動裝置版。
熟悉UCM，以及如何與其他 Windows 驅動程序互動。請參閱架構：Windows 系統的 USB Type-C 設計。
熟悉 Windows Driver Foundation (WDF) 。建議閱讀：使用 Windows Driver Foundation 開發驅動程式，其作者為Peny Orwick 和 Guy Smith。

UCM 類別延伸模組所提供的服務摘要

UCM 類別延伸模組可讓操作系統知道數據與電源角色、充電等級和交涉的 PD 合約變更。當客戶端驅動程式與硬體互動時，必須在發生這些變更時通知類別延伸模組。類別延伸模組提供一組方法，可供用戶端驅動程式用來傳送本主題所討論的通知 () 。以下是所提供的服務：

數據角色設定

在USB Type-C系統上， (主機或函式) 的數據角色取決於連接器的CC針腳狀態。您的用戶端驅動程式會讀取 CC 行 (請參閱架構：Windows 系統) 狀態的 USB Type-C 設計，以判斷埠是否已解析為上游面向埠 (UFP) 或下游對向埠 (UFP) 。它會向類別延伸模組報告該資訊，以便向USB角色交換器驅動程序報告目前的角色。

注意

USB 角色交換器驅動程式用於 Windows 10 行動裝置版系統上。在傳統型版本的 Windows 10 上，類別延伸模組與角色交換器驅動程式之間的通訊是選擇性的。這類系統可能不會使用雙重角色控制器，在此情況下，不會使用角色交換器驅動程式。

電源角色和充電

您的用戶端驅動程式會讀取USB Type-C目前的公告，或與合作夥伴連接器交涉 PD 電源合約。

在 Windows 10 行動裝置版系統上，選擇適當措施的決策是軟體輔助的。用戶端驅動程式會將合約資訊回報給類別延伸模組，以便將充電等級傳送至充電仲裁驅動程式 (CAD.sys) 。 CAD 會選取要使用的目前層級，並將充電等級資訊轉送至電池子系統。
在桌面版本的 Windows 10 系統上，硬體會選取適當的電源。用戶端驅動程式可以選擇取得該資訊，並將其轉送到類別延伸模組。或者，該邏輯可由不同的驅動程序實作。

數據和電源角色變更

交涉 PD 合約之後，數據角色和電源角色可能會變更。您的用戶端驅動程式或合作夥伴連接器可能會起始該變更。用戶端驅動程式會向類別延伸模組報告該資訊，以便據以重新設定專案。

數據和/或電源角色更新

操作系統可能會決定目前的數據角色不正確。在此情況下，類別擴充功能會呼叫驅動程式的回呼函式，以執行必要的角色交換作業。

Microsoft 提供的 USB Type-C 原則管理員會監視 USB Type-C 連接器的活動。 Windows 1809 版引進了一組程式設計介面，可用來將用戶端驅動程式寫入原則管理員。用戶端驅動程式可以參與 USB Type-C 連接器的原則決策。透過此集合，您可以選擇撰寫內核模式導出驅動程式或使用者模式驅動程式。如需詳細資訊，請參閱撰寫USB Type-C原則管理員客戶端驅動程式。

用戶端驅動程式的預期行為

您的用戶端驅動程式負責下列工作：

偵測 CC 行上的變更，並判斷合作夥伴的類型，例如 UFP、DFP 和其他專案。若要這樣做，驅動程式必須實作USB Type-C規格中所定義的完整 Type-C 狀態機器。
根據在 CC 行上偵測到的方向設定您的 Mux。這包括開啟您的 PD 傳輸器/接收者，以及處理和回應 PD 訊息。若要這樣做，驅動程式必須實作 USB 電源傳遞 2.0 規格中所定義的完整 PD 接收器和傳輸器狀態機器。
進行 PD 原則決策，例如交涉合約 (作為來源或接收) 、角色交換和其他專案。用戶端驅動程式負責判斷最適當的合約。
公告並交涉替代模式，並在偵測到替代模式時設定 Mux。用戶端驅動程式負責決定要交涉的替代模式。
透過連接器控制 VBus/VConn。

1. (UCMCONNECTOR) 初始化 UCM 連接器物件

UCM 連接器物件 (UCMCONNECTOR) 代表 USB Type-C 連接器，而且是 UCM 類別延伸模組與用戶端驅動程式之間的主要句柄。對象會追蹤連接器的作業模式和電源功能。

以下是客戶端驅動程式擷取連接器 UCMCONNECTOR 句柄的順序摘要。在驅動程式的中執行這些工作

藉由將參考傳遞至UCM_MANAGER_CONFIG結構，呼叫 UcmInitializeDevice。驅動程式必須在 EVT_WDF_DRIVER_DEVICE_ADD回 呼函式中呼叫這個方法，才能呼叫 WdfDeviceCreate。
在 UCM_CONNECTOR_TYPEC_CONFIG 結構中指定USB Type-C連接器的初始化參數。這包括連接器的作業模式，無論是下游面向的埠、上游面向的埠，還是具備雙重角色功能。當連接器是電源來源時，它也會指定USB Type-C目前層級。 USB Type-C 連接器可以設計成可以執行 3.5 公厘音訊插孔。如果硬體支援此功能，則必須據以初始化連接器物件。

在結構中，您也必須註冊客戶端驅動程式的回呼函式來處理數據角色。

這個回呼函式會與 UCM 類別延伸模組叫用的連接器對象相關聯。用戶端驅動程序必須實作此函式。

EVT_UCM_CONNECTOR_SET_DATA_ROLE 連接到夥伴連接器時，將連接器的數據角色交換至指定的角色。
如果您的用戶端驅動程式想要具備 PD 功能，也就是處理連接器的 Power Delivery 2.0 硬體實作，您也必須初始化指定 PD 初始化參數 的UCM_CONNECTOR_PD_CONFIG 結構。這包括電源流程，無論是連接器是電源接收或來源。

在結構中，您也必須註冊客戶端驅動程式的回呼函式來處理電源角色。

這個回呼函式會與 UCM 類別延伸模組叫用的連接器對象相關聯。用戶端驅動程序必須實作此函式。

EVT_UCM_CONNECTOR_SET_POWER_ROLE 將連接器的電源角色設定為附加至夥伴連接器時的指定角色。
呼叫 UcmConnectorCreate 並擷取連接器的 UCMCONNECTOR 句柄。呼叫 WdfDeviceCreate，確定您在用戶端驅動程式建立架構裝置對象之後呼叫此方法。此呼叫的適當位置可以是驅動程式 的EVT_WDF_DEVICE_PREPARE_HARDWARE 或 EVT_WDF_DEVICE_D0_ENTRY。

EVT_UCM_CONNECTOR_SET_DATA_ROLE     EvtSetDataRole;

NTSTATUS
EvtDevicePrepareHardware(
    WDFDEVICE Device,
    WDFCMRESLIST ResourcesRaw,
    WDFCMRESLIST ResourcesTranslated
    )
{
    NTSTATUS status = STATUS_SUCCESS;
    PDEVICE_CONTEXT devCtx;
    UCM_MANAGER_CONFIG ucmCfg;
    UCM_CONNECTOR_CONFIG connCfg;
    UCM_CONNECTOR_TYPEC_CONFIG typeCConfig;
    UCM_CONNECTOR_PD_CONFIG pdConfig;
    WDF_OBJECT_ATTRIBUTES attr;
    PCONNECTOR_CONTEXT connCtx;

    UNREFERENCED_PARAMETER(ResourcesRaw);
    UNREFERENCED_PARAMETER(ResourcesTranslated);

    TRACE_FUNC_ENTRY();

    devCtx = GetDeviceContext(Device);

    if (devCtx->Connector)
    {
        goto Exit;
    }

    //
    // Initialize UCM Manager
    //
    UCM_MANAGER_CONFIG_INIT(&ucmCfg);

    status = UcmInitializeDevice(Device, &ucmCfg);
    if (!NT_SUCCESS(status))
    {
        TRACE_ERROR(
            "UcmInitializeDevice failed with %!STATUS!.",
            status);
        goto Exit;
    }

    TRACE_INFO("UcmInitializeDevice() succeeded.");

    //
    // Create a USB Type-C connector #0 with PD
    //
    UCM_CONNECTOR_CONFIG_INIT(&connCfg, 0);

    UCM_CONNECTOR_TYPEC_CONFIG_INIT(
        &typeCConfig,
        UcmTypeCOperatingModeDrp,
        UcmTypeCCurrentDefaultUsb | UcmTypeCCurrent1500mA | UcmTypeCCurrent3000mA);

    typeCConfig.EvtSetDataRole = EvtSetDataRole;

    UCM_CONNECTOR_PD_CONFIG_INIT(&pdConfig, UcmPowerRoleSink | UcmPowerRoleSource);

    connCfg.TypeCConfig = &typeCConfig;
    connCfg.PdConfig = &pdConfig;

    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attr, CONNECTOR_CONTEXT);

    status = UcmConnectorCreate(Device, &connCfg, &attr, &devCtx->Connector);
    if (!NT_SUCCESS(status))
    {
        TRACE_ERROR(
            "UcmConnectorCreate failed with %!STATUS!.",
            status);
        goto Exit;
    }

    connCtx = GetConnectorContext(devCtx->Connector);

    UcmEventInitialize(&connCtx->EventSetDataRole);

    TRACE_INFO("UcmConnectorCreate() succeeded.");

Exit:

    TRACE_FUNC_EXIT();
    return status;
}

2.回報合作夥伴連接器附加事件

偵測到夥伴連接器的連線時，客戶端驅動程序必須呼叫 UcmConnectorTypeCAttach 。此呼叫會通知 UCM 類別延伸模組，以進一步通知作業系統。此時，系統可能會開始在USB Type-C 層級充電。

UCM 類別延伸模組也會通知 USB 角色切換驅動程式 (URS) 。根據合作夥伴的類型，URS 會在主機角色或函式角色中設定控制器。在呼叫此方法之前，請確定系統上的 Mux 已正確設定。否則，如果系統處於函式角色，則會以不正確的速度連線， (高速而非 SuperSpeed) 。

        UCM_CONNECTOR_TYPEC_ATTACH_PARAMS attachParams;

        UCM_CONNECTOR_TYPEC_ATTACH_PARAMS_INIT(
            &attachParams,
            UcmTypeCPortStateDfp);
        attachParams.CurrentAdvertisement = UcmTypeCCurrent1500mA;

        status = UcmConnectorTypeCAttach(
                    Connector,
                    &attachParams);
        if (!NT_SUCCESS(status))
        {
            TRACE_ERROR(
                "UcmConnectorTypeCAttach() failed with %!STATUS!.",
                status);
            goto Exit;
        }

        TRACE_INFO("UcmConnectorTypeCAttach() succeeded.");

3.報告 USB Type-C 公告變更

在初始附加事件中，合作夥伴連接器會傳送目前的公告。如果公告在合作夥伴是 USB Type-C 下游面向埠時，指定合作夥伴連接器的目前層級。否則，公告會指定本機連接器的目前層級，由 UCMCONNECTOR 句柄 (本機連接器) 表示。此初始公告可能會在連線存留期期間變更。用戶端驅動程序必須監視這些變更。

如果本機連接器是電源接收器，且目前的公告變更，用戶端驅動程序必須偵測目前公告中的變更，並將其回報給類別延伸模組。在 Windows 10 行動裝置版系統上，CAD.sys 和電池子系統會使用該資訊來調整從來源繪製的目前數量。若要向類別延伸模塊報告目前層級的變更，用戶端驅動程序必須呼叫 UcmConnectorTypeCCurrentAdChanged。

4.回報新的交涉 PD 合約

如果您的連接器支援 PD，在初始附加事件之後，連接器與其夥伴連接器之間會傳送 PD 訊息。這兩個合作夥伴之間會交涉 PD 合約，決定連接器可以繪製或允許合作夥伴繪製的目前層級。每次 PD 合約變更時，用戶端驅動程式都必須呼叫這些方法，以向類別延伸模組報告變更。

每當客戶端驅動程式取得來源功能公告時，用戶端驅動程序必須呼叫這些方法， (未經要求或從合作夥伴) 。只有在合作夥伴是來源時，本機連接器 (接收) 才會從合作夥伴取得未經請求的公告。此外，即使合作夥伴目前是接收) ，本機連接器也可以明確地向合作夥伴要求能夠成為來源 (的來源功能。交換的方法是將 Get_Source_Caps 訊息傳送給合作夥伴。
- UcmConnectorPdPartnerSourceCaps 報告合作夥伴連接器公告的來源功能。
- UcmConnectorPdConnectionStateChanged 以報告合約的詳細數據。合約會在Power Delivery 2.0 規格中定義的要求資料物件中描述。
相反地，每次本機連接器 (來源) 向合作夥伴公告來源功能時，用戶端驅動程式都必須呼叫這些方法。此外，當本機連接器收到來自合作夥伴 的Get_Source_Caps 訊息時，它必須回應本機連接器的來源功能。
- UcmConnectorPdSourceCaps ，向合作夥伴連接器報告系統公告的來源功能。
- UcmConnectorPdConnectionStateChanged ，以報告目前交涉 PD 合約的連接功能。

5.報告電池充電狀態

如果充電等級不足，客戶端驅動程式可以通知UCM類別延伸模組。類別延伸模組會將此資訊報告給操作系統。系統會使用該資訊來顯示使用者通知，指出充電器未以最佳方式充電系統。這些方法可以報告充電狀態：

這些方法會指定充電狀態。如果回報的層級為 UcmChargingStateSlowCharging 或 UcmChargingStateTrickleCharging (請參閱 UCM_CHARGING_STATE) ，操作系統會顯示使用者通知。

6.報告PR_Swap/DR_Swap事件

如果連接器收到電源角色 (PR_Swap) 或數據角色， (DR_Swap) 從合作夥伴交換訊息，用戶端驅動程序必須通知 UCM 類別延伸模組。

UcmConnectorDataDirectionChanged

在處理 PD DR_Swap訊息之後呼叫此方法。在此呼叫之後，操作系統會將新角色回報給 URS，這會終止現有的角色驅動程式，並載入新角色的驅動程式。
UcmConnectorPowerDirectionChanged

處理 PD PR_Swap訊息之後，呼叫這個方法。 PR_Swap之後，必須重新交涉 PD 合約。用戶端驅動程序必須呼叫步驟 4 中所述的方法來報告 PD 合約交涉。

7.實作回呼函式來處理電源和數據角色交換要求

UCM 類別延伸模組可能會取得變更連接器數據或電源方向的要求。在此情況下，如果連接器實作 PD) ，它會叫用用戶端驅動程式的 EVT_UCM_CONNECTOR_SET_DATA_ROLE 實作，並 EVT_UCM_CONNECTOR_SET_POWER_ROLE 回呼函式 (。用戶端驅動程式先前已在呼叫 UcmConnectorCreate 中註冊這些函式。

用戶端驅動程式會使用硬體介面來執行角色交換作業。

EVT_UCM_CONNECTOR_SET_DATA_ROLE

在回呼實作中，用戶端驅動程序應該會：

將 PD DR_Swap訊息傳送至埠夥伴。
呼叫 UcmConnectorDataDirectionChanged 以通知類別延伸模組訊息序列已成功或失敗。

EVT_UCM_CONNECTOR_SET_DATA_ROLE     EvtSetDataRole;

NTSTATUS
EvtSetDataRole(
    UCMCONNECTOR  Connector,
    UCM_TYPE_C_PORT_STATE DataRole
    )
{
    PCONNECTOR_CONTEXT connCtx;

    TRACE_INFO("EvtSetDataRole(%!UCM_TYPE_C_PORT_STATE!) Entry", DataRole);

    connCtx = GetConnectorContext(Connector);

    TRACE_FUNC_EXIT();

    return STATUS_SUCCESS;
}

EVT_UCM_CONNECTOR_SET_POWER_ROLE

在回呼實作中，用戶端驅動程序應該會：

將 PD PR_Swap訊息傳送至埠夥伴。
呼叫 UcmConnectorPowerDirectionChanged 以通知類別延伸模組訊息序列已成功或失敗。

EVT_UCM_CONNECTOR_SET_POWER_ROLE     EvtSetPowerRole;

NTSTATUS
EvtSetPowerRole(
    UCMCONNECTOR Connector,
    UCM_POWER_ROLE PowerRole
    )
{
    PCONNECTOR_CONTEXT connCtx;

    TRACE_INFO("EvtSetPowerRole(%!UCM_POWER_ROLE!) Entry", PowerRole);

    connCtx = GetConnectorContext(Connector);

    //PR_Swap operation.

    TRACE_FUNC_EXIT();

    return STATUS_SUCCESS;
}

注意

用戶端驅動程式可以異步呼叫 UcmConnectorDataDirectionChanged 和 UcmConnectorPowerDirectionChanged ，而不是從回呼線程呼叫。在一般實作中，類別延伸模組會叫用回呼函式，導致客戶端驅動程式起始硬體交易以傳送訊息。當交易完成時，硬體會通知驅動程式。驅動程式會呼叫這些方法來通知類別延伸模組。

8.回報合作夥伴連接器中斷連結事件

當與夥伴連接器的連線結束時，用戶端驅動程序必須呼叫 UcmConnectorTypeCDetach 。此呼叫會通知 UCM 類別延伸模組，以進一步通知作業系統。

使用案例範例：連線到計算機的行動裝置

當執行 Windows 10 行動裝置版的裝置透過 USB Type-C 連線連接到執行傳統型版本 Windows 10 的電腦時，操作系統可確保行動裝置是上游面向埠 (UFP) ，因為 MTP 僅適用於該方向。在此案例中，以下是數據角色更正的順序：

在行動裝置上執行的用戶端驅動程式會呼叫 UcmConnectorTypeCAttach 回報附加事件，並將合作夥伴連接器回報為下游面向埠 (UFP) 。
用戶端驅動程式會呼叫 UcmConnectorPdPartnerSourceCaps 和 UcmConnectorPdConnectionStateChanged 來報告 PD 合約。
UCM 類別延伸模組會通知 USB 裝置端驅動程式，導致這些驅動程式回應主機的列舉。操作系統資訊會透過USB交換。
UCM 類別延伸模組 UcmCx 會叫用用戶端驅動程式的回呼函式來變更角色： EVT_UCM_CONNECTOR_SET_DATA_ROLE 和 EVT_UCM_CONNECTOR_SET_POWER_ROLE。

注意

如果兩個 Windows 10 行動裝置版裝置彼此連線，則不會執行角色交換，而且使用者會收到連線不是有效連線的通知。

開發適用於 USB Type-C 連接器的 Windows 驅動程式

共用方式為

寫入USB Type-C 連接器驅動程式

摘要

官方規格

適用於

WDF 版本

重要 API

開始之前

UCM 類別延伸模組所提供的服務摘要

數據角色設定

電源角色和充電

數據和電源角色變更

數據和/或電源角色更新

用戶端驅動程式的預期行為

1. (UCMCONNECTOR) 初始化 UCM 連接器物件

2.回報合作夥伴連接器附加事件

3.報告 USB Type-C 公告變更

4.回報新的交涉 PD 合約

5.報告電池充電狀態

6.報告PR_Swap/DR_Swap事件

7.實作回呼函式來處理電源和數據角色交換要求

8.回報合作夥伴連接器中斷連結事件

使用案例範例：連線到計算機的行動裝置

意見反應

其他資源

共用方式為

寫入USB Type-C 連接器驅動程式

摘要

官方規格

適用於

WDF 版本

重要 API

開始之前

UCM 類別延伸模組所提供的服務摘要

數據角色設定

電源角色和充電

數據和電源角色變更

數據和/或電源角色更新

用戶端驅動程式的預期行為

1. (UCMCONNECTOR) 初始化 UCM 連接器物件

2.回報合作夥伴連接器附加事件

3.報告 USB Type-C 公告變更

4.回報新的交涉 PD 合約

5.報告電池充電狀態

6.報告PR_Swap/DR_Swap事件

7.實作回呼函式來處理電源和數據角色交換要求

8.回報合作夥伴連接器中斷連結事件

使用案例範例：連線到計算機的行動裝置

相關主題

意見反應

其他資源