NFC CX 快速入門指南

本指南示範如何使用 NFC 類別擴充(NFC CX)驅動程式撰寫 NFC 功能驅動程式。

Note

在實作中使用類別擴充驅動的驅動程式稱為「客戶端驅動程式」。 也就是說,是類別擴充驅動程式的客戶端。

Prerequisites

客戶司機職責

NFC CX 驅動程式負責處理發送給驅動程式的 I/O 請求並產生相關的 NCI 指令封包。 用戶端驅動負責將這些 NCI 封包傳送給 NFC 控制器,並將 NCI 回應封包回傳回 NFC CX 驅動程式。

由客戶端驅動程式決定如何將 NCI 封包傳送給 NFC 控制器。 此過程會依所使用的硬體匯流排類型而有所不同。 NFC 控制器常用的匯流排包括 I2C、SPI 和 USB。

完整專案程式碼

完整範例程式碼可在 GitHub 取得:NFC CX 客戶端驅動程式範例。

專案設定

  1. 在 Visual Studio 中,建立一個新的「使用者模式驅動程式,空(UMDF V2)」專案。

    在 [檔案] 功能表上,指向 [新增],然後選取 [專案]。 在 Visual C++ 節點中,在 Windows 驅動程式 下選擇 WDF,然後選擇使用者模式驅動程式,空(UMDF V2)

    截圖顯示Visual Studio「新Project」對話框,選取「使用者模式驅動程式,空(UMDF V2)」。

  2. 打開 INF 檔案。

    在 方案總管 中,於 >project-name< 節點下方的 Driver Files 資料夾中,雙擊 <project-name>.inf。

  3. 在 INF 檔案中,請依照以下步驟移除自訂裝置類別:

    1. 移除以下兩個部分:

      [ClassInstall32]
      AddReg=SampleClass_RegistryAdd
      
      [SampleClass_RegistryAdd]
      HKR,,,,%ClassName%
      HKR,,Icon,,"-10"
      
    2. 在該 [Strings] 區段下方,移除以下行。

      ClassName="Samples" ; TODO: edit ClassName
      
  4. 在 INF 檔案中,將驅動程式的裝置類別設為 Proximity:

    1. 將 Class 的值改為 Proximity
    2. 將 ClassGuid 的值改為 {5630831C-06C9-4856-B327-F5D32586E060}
      • 這是接近裝置類別的 GUID。
    [Version]
    ...
    Class=Proximity
    ClassGuid={5630831C-06C9-4856-B327-F5D32586E060} ; Proximity class GUID
    ...
    
  5. 在 INF 檔案中,新增對 NFC 類別擴充功能的參照。 這麼做可以確保 Windows 驅動程式框架(WDF)在客戶端驅動程式載入時,會載入 NFC CX 驅動程式。

    1. 找出區段 <project-name>_Install。
    2. 新增 UmdfExtensions=NfcCx0102。
    [<project-name>_Install]
    ...
    UmdfExtensions=NfcCx0102
    
  6. 在驅動程式建置設定中,連結到 NFC 類別擴充功能。 這麼做可以確保 NFC CX API 在程式碼編譯過程中可用。

    1. 在 方案總管 中,右鍵點擊專案,選擇屬性。 在 設定屬性 的 驅動程式設定 下,選取 NFC。
    2. 確保 設定 設定為 All Configurations。
    3. 確保將 Platform 設為 All Platforms。
    4. 將 連結至 NFC 類別擴充功能 設為 Yes。

    Visual Studio 對話框:MyNfcDriver 屬性頁面,顯示「連結到 NFC 類別擴充功能」設定為「是」。

  7. 新增名為 Driver.cpp 的檔案到專案中。

  8. 在Driver.cpp中建立一個DriverEntry常式。 這是驅動程式的進入點。 其主要目的是初始化 WDF 並註冊 EvtDriverDeviceAdd 回呼函式。

    #include <windows.h>
    #include <wdf.h>
    
    #include "Device.h" // created in Step 9
    
    // The entry point for the driver.
    extern "C" NTSTATUS DriverEntry(
        _In_ PDRIVER_OBJECT DriverObject,
        _In_ PUNICODE_STRING RegistryPath
        )
    {
        NTSTATUS status = STATUS_SUCCESS;
    
        // Specify `DeviceContext::AddDevice` as the
        // `EvtDriverDeviceAdd` function for the driver.
        WDF_DRIVER_CONFIG driverConfig;
        WDF_DRIVER_CONFIG_INIT(&driverConfig, DeviceContext::AddDevice);
    
        // Initialize WDF.
        status = WdfDriverCreate(
            DriverObject,
            RegistryPath,
            WDF_NO_OBJECT_ATTRIBUTES,
            &driverConfig,
            WDF_NO_HANDLE);
        if (!NT_SUCCESS(status))
        {
            return status;
        }
    
        return STATUS_SUCCESS;
    }
    
  9. 新增兩個名為 Device.cpp 和 Device.h 的檔案到專案中。

  10. 在 Device.h中,定義類別 DeviceContext 。

    #pragma once
    
    #include <windows.h>
    #include <wdf.h>
    #include <NfcCx.h>
    
    // The class that will store the driver's custom state for
    // a device instance.
    class DeviceContext
    {
    public:
        // Implementation of `EvtDriverDeviceAdd`.
        static NTSTATUS AddDevice(
            _In_ WDFDRIVER Driver,
            _Inout_ PWDFDEVICE_INIT DeviceInit);
    
    private:
        // Implementation of `EvtDevicePrepareHardware`.
        static NTSTATUS PrepareHardware(
            _In_ WDFDEVICE Device,
            _In_ WDFCMRESLIST ResourcesRaw,
            _In_ WDFCMRESLIST ResourcesTranslated);
    
        // Implementation of `EvtDeviceReleaseHardware`.
        static NTSTATUS ReleaseHardware(
            _In_ WDFDEVICE Device,
            _In_ WDFCMRESLIST ResourcesTranslated);
    
        // Implementation of `EvtDeviceD0Entry`.
        static NTSTATUS D0Entry(
            _In_ WDFDEVICE Device,
            _In_ WDF_POWER_DEVICE_STATE PreviousState);
    
        // Implementation of `EvtDeviceD0Exit`.
        static NTSTATUS D0Exit(
            _In_ WDFDEVICE Device,
            _In_ WDF_POWER_DEVICE_STATE TargetState);
    
        // Implementation of `EvtNfcCxWriteNciPacket`.
        static void WriteNciPacket(
            _In_ WDFDEVICE Device,
            _In_ WDFREQUEST Request);
    };
    
    // Define the `DeviceGetContext` function.
    WDF_DECLARE_CONTEXT_TYPE_WITH_NAME(DeviceContext, DeviceGetContext);
    
  11. 在 Device.cpp 中,開始定義 DeviceContext::AddDevice 函數。

    #include "Device.h"
    
    NTSTATUS DeviceContext::AddDevice(
        _In_ WDFDRIVER Driver,
        _Inout_ PWDFDEVICE_INIT DeviceInit)
    {
        NTSTATUS status;
    
    
  12. 設定 NFC CX 裝置組態。 裝置配置包含提供 EvtNfcCxWriteNciPacket 回呼函式。 此回調接收來自 NFC CX 驅動程式的 NCI 封包,客戶端驅動程式應將其轉送給 NFC 控制器。

        // Create the NfcCx config.
        NFC_CX_CLIENT_CONFIG nfcCxConfig;
        NFC_CX_CLIENT_CONFIG_INIT(&nfcCxConfig, NFC_CX_TRANSPORT_CUSTOM);
        nfcCxConfig.EvtNfcCxWriteNciPacket = WriteNciPacket;
        nfcCxConfig.DriverFlags = NFC_CX_DRIVER_ENABLE_EEPROM_WRITE_PROTECTION;
    
        // Set the NfcCx config.
        status = NfcCxDeviceInitConfig(DeviceInit, &nfcCxConfig);
        if (!NT_SUCCESS(status))
        {
            return status;
        }
    
  13. 註冊客戶端驅動程式所需的 PnP 電源回呼。

    典型的客戶端驅動程式通常會需要 EvtDevicePrepareHardware、EvtDeviceReleaseHardware、EvtDeviceD0Entry 和 EvtDeviceD0Exit 函式。 需求會依客戶驅動程式如何處理電源管理而有所不同。

        // Create the PnP power callbacks configuration.
        WDF_PNPPOWER_EVENT_CALLBACKS pnpCallbacks;
        WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&pnpCallbacks);
        pnpCallbacks.EvtDevicePrepareHardware = PrepareHardware;
        pnpCallbacks.EvtDeviceReleaseHardware = ReleaseHardware;
        pnpCallbacks.EvtDeviceD0Entry = D0Entry;
        pnpCallbacks.EvtDeviceD0Exit = D0Exit;
    
        // Set the PnP power callbacks.
        WdfDeviceInitSetPnpPowerEventCallbacks(DeviceInit, &pnpCallbacks);
    
  14. 呼叫 WdfDeviceCreate 這個函式來建立物件 WDFDEVICE 。

        // Create WDF object attributes for the WDFDEVICE object.
        WDF_OBJECT_ATTRIBUTES deviceAttributes;
        WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&deviceAttributes, DeviceContext);
    
        // Create the device.
        WDFDEVICE device;
        status = WdfDeviceCreate(&DeviceInit, &deviceAttributes, &device);
        if (!NT_SUCCESS(status))
        {
            return status;
        }
    
  15. 呼叫 NfcCxDeviceInitialize 函式。

    此函式應在 WDFDEVICE 物件建立後呼叫,讓 NFC CX 驅動程式完成裝置實例的初始化。

        // Let NFC CX finish initializing the device instance.
        status = NfcCxDeviceInitialize(device);
        if (!NT_SUCCESS(status))
        {
            return status;
        }
    
  16. 呼叫 NfcCxSetRfDiscoveryConfig 以指定 NFC 控制器所支援的 NFC 技術與通訊協定。

        // Create the RF config. (Enable everything.)
        NFC_CX_RF_DISCOVERY_CONFIG discoveryConfig;
        NFC_CX_RF_DISCOVERY_CONFIG_INIT(&discoveryConfig);
        discoveryConfig.PollConfig =
            NFC_CX_POLL_NFC_A | NFC_CX_POLL_NFC_B |
            NFC_CX_POLL_NFC_F_212 | NFC_CX_POLL_NFC_F_424 |
            NFC_CX_POLL_NFC_15693 | NFC_CX_POLL_NFC_ACTIVE |
            NFC_CX_POLL_NFC_A_KOVIO;
        discoveryConfig.NfcIPMode =
            NFC_CX_NFCIP_NFC_A | NFC_CX_NFCIP_NFC_F_212 |
            NFC_CX_NFCIP_NFC_F_424 | NFC_CX_NFCIP_NFC_ACTIVE |
            NFC_CX_NFCIP_NFC_ACTIVE_A | NFC_CX_NFCIP_NFC_ACTIVE_F_212 |
            NFC_CX_NFCIP_NFC_ACTIVE_F_424;
        discoveryConfig.NfcIPTgtMode =
            NFC_CX_NFCIP_TGT_NFC_A | NFC_CX_NFCIP_TGT_NFC_F |
            NFC_CX_NFCIP_TGT_NFC_ACTIVE_A | NFC_CX_NFCIP_TGT_NFC_ACTIVE_F;
        discoveryConfig.NfcCEMode =
            NFC_CX_CE_NFC_A | NFC_CX_CE_NFC_B |
            NFC_CX_CE_NFC_F;
    
        // Set the RF config.
        status = NfcCxSetRfDiscoveryConfig(device, &discoveryConfig);
        if (!NT_SUCCESS(status))
        {
            return status;
        }
    
  17. 結束 DeviceContext::AddDevice 這個函式。

        return STATUS_SUCCESS;
    }
    
  18. 實作 PrepareHardware 和 ReleaseHardware 回調函式。

    這兩個函式用於初始化和解除初始化分配給 NFC 控制器裝置實例的硬體資源。 它們的實作取決於裝置所連接的匯流排類型(例如 I2C、SPI 和 USB)。

    NTSTATUS DeviceContext::PrepareHardware(
        _In_ WDFDEVICE Device,
        _In_ WDFCMRESLIST ResourcesRaw,
        _In_ WDFCMRESLIST ResourcesTranslated)
    {
        // FIX ME: Initialize hardware resources.
        return STATUS_SUCCESS;
    }
    
    NTSTATUS DeviceContext::ReleaseHardware(
        _In_ WDFDEVICE Device,
        _In_ WDFCMRESLIST ResourcesTranslated)
    {
        // FIX ME: Uninitialize hardware resources.
        return STATUS_SUCCESS;
    }
    
  19. 在適當時間以 HostActionStart 和 HostActionStop 呼叫 NfcCxHardwareEvent 函式,以啟動及停止 NCI 狀態機。

    有些驅動程式會在 D0Entry 和 D0Exit PnP 電源回調時這麼做。 不過這會依客戶端驅動程式如何處理電源管理而有所不同。

    // Device exiting low power state (or is booting up).
    NTSTATUS DeviceContext::D0Entry(
        _In_ WDFDEVICE Device,
        _In_ WDF_POWER_DEVICE_STATE PreviousState)
    {
        (void)PreviousState;
    
        NTSTATUS status;
    
        // Invoke the HostActionStart event, so that the NFC CX initializes
        // the NFC Controller.
        NFC_CX_HARDWARE_EVENT eventArgs = {};
        eventArgs.HostAction = HostActionStart;
    
        status = NfcCxHardwareEvent(Device, &eventArgs);
        if (!NT_SUCCESS(status))
        {
            return status;
        }
    
        return STATUS_SUCCESS;
    }
    
    // Device entering low power state.
    NTSTATUS DeviceContext::D0Exit(
        _In_ WDFDEVICE Device,
        _In_ WDF_POWER_DEVICE_STATE TargetState)
    {
        (void)TargetState;
    
        NTSTATUS status;
    
        // Trigger the HostActionStop event, so that the NFC CX
        // uninitializes the NFC Controller.
        NFC_CX_HARDWARE_EVENT eventArgs = {};
        eventArgs.HostAction = HostActionStop;
    
        status = NfcCxHardwareEvent(Device, &eventArgs);
        if (!NT_SUCCESS(status))
        {
            return status;
        }
    
        return STATUS_SUCCESS;
    }
    
  20. 實作這個 WriteNciPacket 函式。

    當有 NCI 封包要傳送給 NFC 控制器時,這個回呼函式會由 NFC CX 呼叫。

    void DeviceContext::WriteNciPacket(
        _In_ WDFDEVICE Device,
        _In_ WDFREQUEST Request)
    {
        NTSTATUS status;
    
        // Get the NCI packet as a raw byte buffer.
        void* nciPacket;
        size_t nciPacketLength;
        status = WdfRequestRetrieveInputBuffer(Request, 0, &nciPacket, &nciPacketLength);
        if (!NT_SUCCESS(status))
        {
            WdfRequestComplete(Request, status);
            return;
        }
    
        // FIX ME: Use the NCI packet in some way.
    
        // FIX ME: Call `WdfRequestComplete` on `Request` with failure
        // or success `NTSTATUS` code.
    };
    
  21. 當 NFC 控制器有要傳送至 NFC CX 的 NCI 封包時,呼叫該 NfcCxNciReadNotification 函式。 通常,這會在硬體事件回撥中進行。

    例如:

Logging

考慮在客戶端驅動程式中加入日誌功能,讓除錯變得更容易。 ETW 追蹤和 WPP 追蹤都是不錯的選擇。