Partager via

Handles d’objet SpbCx

Cette rubrique décrit les handles d’objet définis pour la bibliothèque SPB Framework Extension (SpbCx).

En outre, la DDI SerCx2 utilise deux des types de handle d’objets génériques, WDFDEVICE et WDFREQUEST, définis par le Kernel-Mode Driver Framework (KMDF). Pour plus d’informations sur les types de handle d’infrastructure, consultez Résumé des objets framework.

Cette rubrique décrit les handles d’objet suivants :

Header: Spbcx.h

SPBREQUEST, handle d’objet

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. Pour plus d’informations sur ces méthodes, consultez Framework Request Objects.

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.

Handle d’objet 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.

Le pilote du contrôleur SPB effectue toutes les opérations spécifiques au matériel pour un périphérique de contrôleur 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. La fonction peut utiliser ce handle pour récupérer les informations de ressource spécifiques à la connexion (par exemple, l’adresse de l’appareil) à partir du gestionnaire 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

Les clients ont un mode exclusif pour accéder aux appareils cibles. Un seul client peut avoir une connexion à un appareil cible particulier à la fois. SpbCx ensures that only one SPBTARGET handle exists for a target device address on the bus. Cette restriction est nécessaire, car SpbCx ne prend pas en charge l’entrelacement des requêtes d’E/S envoyées par deux clients ou plus à un appareil cible. Si un appareil cible doit être en mesure de recevoir des demandes de plusieurs clients, cet appareil nécessite un pilote MUX( distinct du pilote du contrôleur) qui peut interagir correctement les opérations demandées.

Interopérabilité avec KMDF

Les méthodes de prise en charge des pilotes SerCx2 et les fonctions de rappel d’événements SpbCx définies par SpbCx utilisent des handles SPBTARGET pour représenter les connexions ouvertes aux appareils cibles sur le bus. 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. Le pilote de contrôleur SPB utilise ce contexte pour suivre les informations spécifiques au pilote du contrôleur et à l’appareil cible. 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