本指南示範如何使用 NFC 類別擴充(NFC CX)驅動程式撰寫 NFC 功能驅動程式。
Note
在實作中使用類別擴充驅動的驅動程式稱為「客戶端驅動程式」。 也就是說,是類別擴充驅動程式的客戶端。
Prerequisites
- 你的 NFC 控制器韌體必須實作 NFC 論壇的 NFC 控制器介面(NCI) 協定。
- Visual Studio 2017(或更新版本)。
- Windows SDK。
- Windows 驅動程式套件 (WDK)。
客戶司機職責
NFC CX 驅動程式負責處理發送給驅動程式的 I/O 請求並產生相關的 NCI 指令封包。 用戶端驅動負責將這些 NCI 封包傳送給 NFC 控制器,並將 NCI 回應封包回傳回 NFC CX 驅動程式。
由客戶端驅動程式決定如何將 NCI 封包傳送給 NFC 控制器。 此過程會依所使用的硬體匯流排類型而有所不同。 NFC 控制器常用的匯流排包括 I2C、SPI 和 USB。
完整專案程式碼
完整範例程式碼可在 GitHub 取得:NFC CX 客戶端驅動程式範例。
專案設定
在 Visual Studio 中,建立一個新的「使用者模式驅動程式,空(UMDF V2)」專案。
在 [檔案] 功能表上,指向 [新增],然後選取 [專案]。 在 Visual C++ 節點中,在 Windows 驅動程式 下選擇 WDF,然後選擇使用者模式驅動程式,空(UMDF V2)
打開 INF 檔案。
在 方案總管 中,於 >project-name< 節點下方的 Driver Files 資料夾中,雙擊 <project-name>.inf。
在 INF 檔案中,請依照以下步驟移除自訂裝置類別:
移除以下兩個部分:
[ClassInstall32] AddReg=SampleClass_RegistryAdd [SampleClass_RegistryAdd] HKR,,,,%ClassName% HKR,,Icon,,"-10"在該
[Strings]區段下方,移除以下行。ClassName="Samples" ; TODO: edit ClassName
在 INF 檔案中,將驅動程式的裝置類別設為 Proximity:
- 將
Class的值改為Proximity - 將
ClassGuid的值改為{5630831C-06C9-4856-B327-F5D32586E060}- 這是接近裝置類別的 GUID。
[Version] ... Class=Proximity ClassGuid={5630831C-06C9-4856-B327-F5D32586E060} ; Proximity class GUID ...- 將
在 INF 檔案中,新增對 NFC 類別擴充功能的參照。 這麼做可以確保 Windows 驅動程式框架(WDF)在客戶端驅動程式載入時,會載入 NFC CX 驅動程式。
- 找出區段
<project-name>_Install。 - 新增
UmdfExtensions=NfcCx0102。
[<project-name>_Install] ... UmdfExtensions=NfcCx0102- 找出區段
在驅動程式建置設定中,連結到 NFC 類別擴充功能。 這麼做可以確保 NFC CX API 在程式碼編譯過程中可用。
- 在 方案總管 中,右鍵點擊專案,選擇屬性。 在 設定屬性 的 驅動程式設定 下,選取 NFC。
- 確保 設定 設定為
All Configurations。 - 確保將 Platform 設為
All Platforms。 - 將 連結至 NFC 類別擴充功能 設為
Yes。
新增名為
Driver.cpp的檔案到專案中。在
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; }新增兩個名為
Device.cpp和Device.h的檔案到專案中。在
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);在
Device.cpp中,開始定義DeviceContext::AddDevice函數。#include "Device.h" NTSTATUS DeviceContext::AddDevice( _In_ WDFDRIVER Driver, _Inout_ PWDFDEVICE_INIT DeviceInit) { NTSTATUS status;設定 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; }註冊客戶端驅動程式所需的 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);呼叫
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; }呼叫
NfcCxDeviceInitialize函式。此函式應在
WDFDEVICE物件建立後呼叫,讓 NFC CX 驅動程式完成裝置實例的初始化。// Let NFC CX finish initializing the device instance. status = NfcCxDeviceInitialize(device); if (!NT_SUCCESS(status)) { return status; }呼叫
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; }結束
DeviceContext::AddDevice這個函式。return STATUS_SUCCESS; }實作
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; }在適當時間以
HostActionStart和HostActionStop呼叫NfcCxHardwareEvent函式,以啟動及停止 NCI 狀態機。有些驅動程式會在
D0Entry和D0ExitPnP 電源回調時這麼做。 不過這會依客戶端驅動程式如何處理電源管理而有所不同。// 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; }實作這個
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. };當 NFC 控制器有要傳送至 NFC CX 的 NCI 封包時,呼叫該
NfcCxNciReadNotification函式。 通常,這會在硬體事件回撥中進行。例如: