共用方式為

GPIO_CLIENT_PREPARE_CONTROLLER回呼函式 （gpioclx.h）

  • 發行項

CLIENT_PrepareController 事件回呼函式會執行讓 GPIO 控制器驅動程式準備好存取一般用途 I/O （GPIO） 控制器所需的任何作業。

語法

GPIO_CLIENT_PREPARE_CONTROLLER GpioClientPrepareController;

NTSTATUS GpioClientPrepareController(
  [in] WDFDEVICE Device,
  [in] PVOID Context,
  [in] WDFCMRESLIST ResourcesRaw,
  [in] WDFCMRESLIST ResourcesTranslated
)
{...}

參數

[in] Device

代表 GPIO 控制器之架構裝置物件的 WDFDEVICE 句柄。

[in] Context

GPIO 控制器驅動程式 裝置內容的指標。

[in] ResourcesRaw

架構資源物件的集合的 WDFCMRESLIST 句柄。 此集合會識別即插即用 （PnP） 管理員指派給 GPIO 控制器裝置的原始（總線相對）硬體資源。

[in] ResourcesTranslated

架構資源物件的集合的 WDFCMRESLIST 句柄。 此集合會識別 PnP 管理員指派給 GPIO 控制器裝置的已翻譯（系統實體）硬體資源。

傳回值

如果呼叫成功，CLIENT_PrepareController 函式會傳回STATUS_SUCCESS。 否則，它會傳回適當的錯誤碼。

言論

GPIO 控制器驅動程式會實作此回呼函式。 GPIO 架構延伸模組 （GpioClx） 會呼叫此函式，以初始化 GPIO 控制器驅動程式所需的硬體資源，以便存取 GPIO 控制器裝置。

ResourcesRaw 和 ResourcesTranslated 參數是原始和已翻譯資源清單的句柄。 這些清單描述 PnP 管理員指派給 Device 參數所指定的 GPIO 控制器裝置的硬體資源。 如需詳細資訊，請參閱 原始和翻譯的資源。

在 CLIENT_PrepareController 回呼期間，GPIO 控制器驅動程式可以從 ResourcesRaw 或 ResourcesTranslated 列表中取得所需的硬體資源。 如果 GPIO 控制器裝置記憶體對應，驅動程式應該將指派給裝置硬體緩存器之總線相對記憶體位址範圍或範圍對應至系統虛擬位址。 如需詳細資訊，請參閱 Bus-Relative 位址對應至虛擬位址。

如果 GPIO 控制器不是記憶體對應，驅動程式的硬體資源會包含連線標識碼，而不是記憶體範圍。 驅動程式會使用此標識碼來開啟 GPIO 控制器的邏輯連線，並透過此連線傳送 I/O 要求，以存取控制器的緩存器。

GpioClx 會連線到 PnP 管理員指派給 GPIO 控制器的任何中斷資源（稍後再中斷連線）。 如果 GpioClx 收到這類中斷資源，則不會從傳遞給 CLIENT_PrepareController 回呼函式的資源清單中移除此中斷資源。 不過，GPIO 控制器驅動程式不應該嘗試連線到 （或更新版本中斷連線）， 它在這些清單中找到的任何中斷資源。

CLIENT_ReleaseController 事件回呼函式會執行無法再存取 GPIO 控制器裝置時所需的作業。 在此回呼期間，GPIO 控制器驅動程式應該釋放在上一個 CLIENT_PrepareController 回呼期間取得的任何硬體資源。

若要註冊驅動程式的 CLIENT_PrepareController 回呼函式，請呼叫 GPIO_CLX_RegisterClient 方法。 這個方法接受作為輸入參數，這是包含 CLIENT_PrepareController 函式指標之 GPIO_CLIENT_REGISTRATION_PACKET 結構的指標。

雖然在 IRQL = PASSIVE_LEVEL 呼叫 CLIENT_PrepareController 回呼函式，但您不應該讓此函式可分頁。 CLIENT_PrepareController 回呼是在硬體平臺中將電源還原至裝置的重要計時路徑，而且基於效能考慮，頁面錯誤不應延遲。

例子

若要定義 CLIENT_PrepareController 回呼函式，您必須先提供函式宣告，以識別您要定義的回呼函式類型。 Windows 提供一組驅動程式的回呼函式類型。 使用回呼函式類型宣告函式有助於 驅動程式的程式代碼分析、靜態驅動程式驗證器 （SDV）和其他驗證工具尋找錯誤，而且是撰寫 Windows作系統驅動程式的需求。

例如，若要定義名為 MyEvtGpioPrepareController的 CLIENT_PrepareController 回呼函式，請使用 GPIO_CLIENT_PREPARE_CONTROLLER 函式類型，如下列程式代碼範例所示：

GPIO_CLIENT_PREPARE_CONTROLLER MyEvtGpioPrepareController;

然後，實作回呼函式，如下所示：

_Use_decl_annotations_
NTSTATUS
  MyEvtGpioPrepareController(
    WDFDEVICE Device,
    PVOID Context,
    WDFCMRESLIST ResourcesRaw,
    WDFCMRESLIST ResourcesTranslated
)
{ ... }

GPIO_CLIENT_PREPARE_CONTROLLER函式類型定義於 Gpioclx.h 頭檔中。 若要在執行程式代碼分析工具時更準確地識別錯誤，請務必將 Use_decl_annotations 批註新增至函式定義。 Use_decl_annotations 批注可確保會使用套用至頭檔中GPIO_CLIENT_PREPARE_CONTROLLER函式類型的批注。 如需函式宣告需求的詳細資訊，請參閱 使用 KMDF 驅動程式的函式角色類型來宣告函式。 如需 Use_decl_annotations的詳細資訊，請參閱 批注函式行為。

要求

要求 價值
最低支援的用戶端 從 Windows 8 開始支援。
目標平臺 桌面
標頭 gpioclx.h
IRQL 在 PASSIVE_LEVEL呼叫。

另請參閱

CLIENT_ReleaseController

GPIO_CLIENT_REGISTRATION_PACKET

GPIO_CLX_RegisterClient