GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS回呼函式 (gpioclx.h)

發行項
02/29/2024

CLIENT_QueryEnabledInterrupts事件回呼函式會查詢一組一組一般用途 I/O (GPIO) 針腳的狀態，以判斷哪些針腳都設定為中斷輸入，並啟用中斷。

語法

GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS GpioClientQueryEnabledInterrupts;

NTSTATUS GpioClientQueryEnabledInterrupts(
  [in] PVOID Context,
  [in] PGPIO_QUERY_ENABLED_INTERRUPTS_PARAMETERS QueryEnabledParameters
)
{...}

參數

[in] Context

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

[in] QueryEnabledParameters

呼叫端配置的 GPIO_QUERY_ENABLED_INTERRUPTS_PARAMETERS 結構的指標。呼叫此函式之前，呼叫端會將銀行標識碼寫入此結構的 BankId 成員，以指定要查詢的 GPIO 針腳銀行。如果成功，函式會將遮罩值寫入這個結構的 EnabledMask 成員，以指出指定的銀行中已啟用哪些中斷。

傳回值

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

備註

從 Windows 8.1 開始，GPIO 控制器驅動程式可以選擇實作CLIENT_QueryEnabledInterrupts回呼函式。如果實作，GPIO 架構延伸模組會呼叫此函式， (GpioClx) ，以判斷 GPIO 針腳的銀行中已啟用哪些中斷。

QueryEnabledParameters 參數會指向呼叫端配置的GPIO_QUERY_ENABLED_INTERRUPTS_PARAMETERS結構。呼叫端會設定這個結構的 BankId 成員值。 CLIENT_QueryEnabledInterrupts函式會寫入結構的 EnabledMask 成員。

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

CLIENT_QueryEnabledInterrupts函式是選擇性的。如果您的驅動程式未實作此函式，請將GPIO_CLIENT_REGISTRATION_PACKET結構CLIENT_QueryEnabledInterrupts成員設定為 NULL。

如果實作 CLIENT_QueryEnabledInterrupts 函式，GpioClx 會使用此函式來改善驅動程式可靠性和診斷。 GpioClx 會呼叫此函式，以確認在 GPIO 控制器上啟用的中斷集符合 GpioClx 的預期。一般而言，不符表示可能導致中斷暴亂的驅動程式 Bug。 GpioClx 會使用此函式在核取 (偵錯) 組建中執行更廣泛的狀態驗證，並減少免費 (零售) 組建對此函式的呼叫數目，以避免影響效能。如果實作，此函式必須直接讀取硬體狀態，而不是讀取快取或軟體維護的狀態版本。

GpioClx 會根據CLIENT_QueryControllerBasicInformation 回呼函 式提供給 GpioClx 的裝置資訊，在 PASSIVE_LEVEL 或 DIRQL 呼叫 CLIENT_QueryEnabledInterrupts 回呼函式。 CLIENT_QueryControllerBasicInformation函式會以CLIENT_CONTROLLER_BASIC_INFORMATION結構的形式提供裝置資訊。如果 MemoryMappedController 旗標位是在這個結構的 Flags 成員中設定，GpioClx 會在 DIRQL 呼叫 CLIENT_QueryEnabledInterrupts 函式，這是 GpioClx 中 ISR 執行所在的 IRQL。否則，會在PASSIVE_LEVEL呼叫此函式。如需此旗標位的詳細資訊，請參閱選擇性和必要的 GPIO 回呼函式。

範例

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

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

GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS MyEvtGpioQueryEnabledInterrupts;

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

_Use_decl_annotations_
NTSTATUS
  MyEvtGpioQueryEnabledInterrupts(
    PVOID Context,
    PGPIO_QUERY_ENABLED_INTERRUPTS_PARAMETERS QueryEnabledParameters
    )
{ ... }

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