次の方法で共有

SpbCx オブジェクト ハンドル

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

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

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

Header: Spbcx.h

SPBREQUEST オブジェクト ハンドル

An SPBREQUEST object handle represents an I/O request that is issued to a target device on the bus.

DECLARE_HANDLE(SPBREQUEST)

The SPBREQUEST object class is derived from the WDFREQUEST object class, which represents an I/O request that is dispatched by the I/O manager. Thus, WdfRequestXxx methods that take WDFREQUEST handle values as parameters accept SPBREQUEST handle values as valid parameter values. これらのメソッドの詳細については、「 フレームワーク要求オブジェクト」を参照してください。

However, some SpbCx methods and callback functions specifically require SPBREQUEST handles as parameters. For such a parameter, substituting a WDFREQUEST handle that is not also an SPBREQUEST handle is an error.

For example, the SpbRequestGetTransferParameters method takes an SPBREQUEST handle as a parameter. To supply, for this parameter, a WDFREQUEST handle that is not also an SPBREQUEST handle is an error. The reason for this requirement is that an SPBREQUEST object must store additional, SPB-specific state information to support I/O transfer sequences. The WDFREQUEST base object class does not provide this support.

During device initialization, your SPB controller driver can assign a per-request context to an SPBREQUEST handle by calling the SpbControllerSetRequestAttributes method.

SPBTARGET オブジェクト ハンドル

An SPBTARGET object handle identifies a logical connection from a client (peripheral driver) to an addressable port or peripheral device on the bus.

DECLARE_HANDLE(SPBTARGET)

For an I2C bus, an SPBTARGET handle corresponds to a specific device address.
For an SPI bus, an SPBTARGET handle corresponds to a device-select line.

Typically, an SPBTARGET object exists from the start of the EvtSpbTargetConnect event callback through the end of the corresponding EvtSpbTargetDisconnect event callback. However, the lifetime of the SPBTARGET object might extend beyond the second callback if the SPB controller driver takes an additional reference on the SPBTARGET object to prevent the object from unexpectedly disappearing during the processing of an I/O request for the target.

SPB コントローラー ドライバーは、SPB コントローラー デバイスのすべてのハードウェア固有の操作を実行します。 When a client sends an IRP_MJ_CREATE request to open a connection to a target on the bus, the SPB framework extension (SpbCx), which manages the I/O queue for the controller driver, passes this request to the SPB controller driver by calling this driver's EvtSpbTargetConnect callback function. This Target parameter of this function is an SPBTARGET handle. この関数は、このハンドルを使用して、PnP マネージャーから接続固有のリソース情報 (デバイス アドレスなど) を取得できます。 When the client sends an IRP_MJ_CLOSE request to close the connection, SpbCx passes this request to the SPB controller driver's EvtSpbTargetDisconnect callback function, which releases these resources.

Exclusive-Mode Access

クライアントには、ターゲット デバイスにアクセスするための排他モードがあります。 特定のターゲット デバイスに一度に接続できるクライアントは 1 つだけです。 SpbCx ensures that only one SPBTARGET handle exists for a target device address on the bus. SpbCx は、2 つ以上のクライアントからターゲット デバイスに送信される I/O 要求のインターリーブをサポートしていないため、この制限が必要です。 ターゲット デバイスが複数のクライアントからの要求を受信できる必要がある場合、このデバイスには、要求された操作を適切にインターリーブできる MUX ドライバー (コントローラー ドライバーとは別) が必要です。

KMDF との相互運用性

SpbCx によって定義される SerCx2 ドライバー サポート メソッドと SpbCx イベント コールバック関数は、SPBTARGET ハンドルを使用して、バス上のターゲット デバイスへの開いている接続を表します。 However, a controller driver must typically call KMDF methods that require WDFFILEOBJECT handles, instead of SPBTARGET handles, to designate target devices.

An SPBTARGET object is similar to a WDFFILEOBJECT object. However, an SPBTARGET object contains additional, SPB-specific information. For example, during the processing of an IOCTL_SPB_EXECUTE_SEQUENCE I/O control request, the SPBTARGET object for the target device tracks the state of the transfers in the I/O transfer sequence.

To obtain the WDFFILEOBJECT handle to a target, the SPB controller driver calls the SpbTargetGetFileObject method. This method accepts, as an input parameter, an SPBTARGET handle to an open target device, and returns the corresponding WDFFILEOBJECT handle to this target.

In accordance with KMDF conventions, the SPB controller driver can attach its own context to the SPBTARGET object for a target device, and this context can include associated EvtCleanupCallback and EvtDestroyCallback callback functions. SPB コントローラー ドライバーは、このコンテキストを使用して、コントローラー ドライバーとターゲット デバイスに固有の情報を追跡します。 In addition, this driver can create child objects of the SPBTARGET object, such as timers, DPCs, or, if needed, I/O requests and I/O queues.

  • Last updated on