GPIO_CLIENT_PREPARE_CONTROLLER コールバック関数 (gpioclx.h)
CLIENT_PrepareController イベント コールバック関数は、汎用 I/O (GPIO) コントローラーに 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 コントローラーがメモリ マップされていない場合、ドライバーのハードウェア リソースには、メモリ範囲ではなく接続 ID が含まれます。 ドライバーは、この ID を使用して 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構造体へのポインターを受け取ります。
CLIENT_PrepareControllerコールバック関数は IRQL = PASSIVE_LEVEL で呼び出されますが、この関数をページング可能にしないでください。 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 以降でサポートされています。 |
| 対象プラットフォーム | デスクトップ |
| Header | gpioclx.h |
| IRQL | PASSIVE_LEVELで呼び出されます。 |