SpbCx オブジェクト ハンドル

  • [アーティクル]

このトピックでは、SPB フレームワーク拡張機能 (SpbCx) ライブラリに定義されているオブジェクト ハンドルについて説明します。

さらに、SerCx2 DDI は、カーネル モード ドライバー フレームワーク (KMDF) によって定義されている WDFDEVICE と WDFREQUEST の 2 つの汎用オブジェクト ハンドル型を使用します。 フレームワーク ハンドル型の詳細については、「フレームワーク オブジェクトの概要」をご参照ください。

このトピックでは、次のオブジェクト ハンドルについて説明します。

ヘッダー: Spbcx.h

SPBREQUEST オブジェクト ハンドル

SPBREQUEST オブジェクト ハンドルは、バス上のターゲット デバイスに対して発行される I/O 要求を表します。

DECLARE_HANDLE(SPBREQUEST)

SPBREQUEST オブジェクト クラスは、WDFREQUEST オブジェクト クラスから派生します。これは、I/O マネージャーによってディスパッチされる I/O 要求を表します。 したがって、WDFREQUEST ハンドル値をパラメーターとして受け取る WdfRequestXxx メソッドは、SPBREQUEST ハンドル値を有効なパラメーター値として受け入れます。 これらのメソッドの詳細については、「フレームワーク要求オブジェクト」を参照してください。

ただし、一部の SpbCx メソッドとコールバック関数では、パラメーターとして SPBREQUEST ハンドルが特に必要となります。 このようなパラメーターの場合、SPBREQUEST ハンドルではない WDFREQUEST ハンドルを置き換える場合はエラーになります。

たとえば、SpbRequestGetTransferParameters メソッドは、SPBREQUEST ハンドルをパラメーターとして受け取ります。 このパラメーターに対して、SPBREQUEST ハンドルでもない WDFREQUEST ハンドルを指定する場合は、エラーになります。 この要件の理由は、SPBREQUEST オブジェクトは、I/O 転送シーケンスをサポートする上で、追加の SPB 固有の状態情報を格納する必要があるということです。 WDFREQUEST 基本オブジェクト クラスでは、このサポートは提供されません。

デバイスの初期化中に、SPB コントローラー ドライバーは SpbControllerSetRequestAttributes メソッドを呼び出すことによって、SPBREQUEST ハンドルに要求ごとのコンテキストを割り当てることができます。

SPBTARGET オブジェクト ハンドル

SPBTARGET オブジェクト ハンドルは、クライアント (周辺機器ドライバー) からバス上のアドレス指定が可能なポートまたは周辺機器への論理接続を識別します。

DECLARE_HANDLE(SPBTARGET)

I2C バスの場合、SPBTARGET ハンドルは特定のデバイス アドレスに対応します。
SPI バスの場合、SPBTARGET ハンドルはデバイス選択回線に対応します。

通常、SPBTARGET オブジェクトは、EvtSpbTargetConnect イベント コールバックの先頭から、対応する EvtSpbTargetDisconnect イベント コールバックの末尾まで存在します。 ただし、SPB コントローラー ドライバーが SPBTARGET オブジェクトの追加参照を取得して、ターゲットの I/O 要求の処理中にオブジェクトが予期せず消えてしまうのを防ぐ場合、SPBTARGET オブジェクトの有効期間は 2 つ目のコールバックを超える可能性があります。

SPB コントローラー ドライバーは、SPB コントローラー デバイスのすべてのハードウェア固有の操作を実行します。 クライアントがバス上のターゲットへの接続を開く IRP_MJ_CREATE 要求を送信すると、コントローラー ドライバーの I/O キューを管理する SPB フレームワーク拡張機能 (SpbCx) は、このドライバーの EvtSpbTargetConnect コールバック関数を呼び出すことによって、この要求を SPB コントローラー ドライバーに渡します。 この関数のこの Target パラメーターは SPBTARGET ハンドルです。 この関数は、このハンドルを使用して、PnP マネージャーから接続固有のリソース情報 (デバイス アドレスなど) を取得できます。 クライアントが接続を閉じる RP_MJ_CLOSE 要求を送信すると、SpbCx は SPB コントローラー ドライバーの EvtSpbTargetDisconnect コールバック関数にこの要求を渡し、これらのリソースを解放します。

排他モードアクセス

クライアントには、ターゲット デバイスにアクセスするための排他モードがあります。 特定のターゲット デバイスに一度に接続できるクライアントは 1 つだけです。 SpbCx は、バス上のターゲット デバイス アドレスに対して 1 つの SPBTARGET ハンドルのみが存在することを保証します。 SpbCx は、2 つ以上のクライアントからターゲット デバイスに送信される I/O 要求のインターリーブをサポートしていないため、この制限が必要となります。 ターゲット デバイスが複数のクライアントからの要求を受信できるようにする必要がある場合、このデバイスには、要求された操作を適切にインターリーブできる MUX ドライバー (コントローラー ドライバーとは別) が必要です。

KMDF との相互運用性

SpbCx によって定義される SerCx2 ドライバー サポート メソッドと SpbCx イベント コールバック関数は、SPBTARGET ハンドルを使用して、バス上のターゲット デバイスへのオープンな接続を表します。 ただし、コントローラー ドライバーは通常、ターゲット デバイスを指定するために、SPBTARGET ハンドルではなく WDFFILEOBJECT ハンドルを必要とする KMDF メソッドを呼び出す必要があります。

SPBTARGET オブジェクトは、WDFFILEOBJECT オブジェクトに似ています。 ただし、SPBTARGET オブジェクトには、SPB 固有の追加情報が含まれています。 たとえば、IOCTL_SPB_EXECUTE_SEQUENC I/O 制御要求の処理中に、ターゲット デバイスの SPBTARGET オブジェクトは、I/O 転送シーケンス内の転送の状態を追跡します。

ターゲットに対する WDFFILEOBJECT ハンドルを取得するために、SPB コントローラー ドライバーは SpbTargetGetFileObject メソッドを呼び出します。 このメソッドは、開いているターゲット デバイスに対する SPBTARGET ハンドルを入力パラメーターとして受け取り、対応する WDFFILEOBJECT ハンドルをこのターゲットに返します。

KMDF 規則に従って、SPB コントローラー ドライバーは、ターゲット デバイスの SPBTARGET オブジェクトに独自のコンテキストをアタッチできます。このコンテキストには、関連付けられている EvtCleanupCallback および EvtDestroyCallback コールバック関数を含めることができます。 SPB コントローラー ドライバーは、このコンテキストを使用して、コントローラー ドライバーとターゲット デバイスに固有の情報を追跡します。 さらに、このドライバーは、タイマー、DPC、または必要に応じて、I/O 要求と I/O キューなどの SPBTARGET オブジェクトの子オブジェクトを作成できます。