EVT_SPB_CONTROLLER_SEQUENCE fonction de rappel (spbcx.h)

Article
02/07/2025

La fonction de rappel d’événement evtSpbControllerIoSequence pilote de contrôleur SPB effectue une séquence de transferts de données entre l’appareil cible spécifié et les mémoires tampons fournies avec la requête de séquence.

Syntaxe

EVT_SPB_CONTROLLER_SEQUENCE EvtSpbControllerSequence;

void EvtSpbControllerSequence(
  [in] WDFDEVICE Controller,
  [in] SPBTARGET Target,
  [in] SPBREQUEST Request,
  [in] ULONG TransferCount
)
{...}

Paramètres

[in] Controller

Handle WDFDEVICE pour l’objet d’appareil framework qui représente le contrôleur SPB.

[in] Target

Un SPBTARGET de gérer la cible pour cette requête d’E/S. La cible est un périphérique ou un port attaché au bus. L’extension de framework SPB (SpbCx) a précédemment affecté ce handle à la cible dans le EvtSpbTargetConnect rappel qui a ouvert la connexion à la cible.

[in] Request

Le handle SPBREQUEST à la requête d’E/S. Votre pilote de contrôleur SPB doit effectuer cette requête en effectuant l’opération demandée ou en retournant un état d’erreur. Pour plus d’informations, consultez Remarques.

[in] TransferCount

Nombre de transferts individuels dans cette séquence de transfert d’E/S. Chaque transfert individuel est une opération de lecture ou d’écriture simple.

Valeur de retour

Aucun

Remarques

SpbCx gère la file d’attente d’E/S pour le contrôleur SPB. SpbCx appelle la fonction de rappel evtSpbControllerIoSequence fonction de rappel lorsqu’un client (pilote périphérique) du contrôleur SPB envoie une requête IOCTL_SPB_EXECUTE_SEQUENCE à un appareil cible attaché au bus. La valeur du paramètre requête est un handle qui encapsule cette requête.

Un rappel EvtSpbControllerIoSequence ne retourne pas de valeur d’état. Au lieu de cela, le pilote du contrôleur SPB indique l’état de l’opération de séquence dans l’état d’achèvement de la demande d’E/S.

Un rappel EvtSpbControllerIoSequence est asynchrone. Autrement dit, la fonction de rappel doit lancer l’opération de séquence demandée (ou la première partie de la séquence), puis retourner sans attendre que l’opération se termine. Plus tard, le pilote du contrôleur SPB continue de traiter la requête ou l’achève pendant les DPC d’interruption ou les contrôleurs de domaine du minuteur.

Le pilote du contrôleur SPB peut récupérer les valeurs des paramètres à partir de la requête d’E/S pour déterminer la longueur maximale des transferts dans la séquence. Le pilote peut utiliser cette longueur pour allouer des ressources DMA qu’il peut réutiliser pour chaque transfert dans la séquence.

Le pilote du contrôleur SPB peut appeler la méthode SpbRequestGetTransferParameters pour récupérer les paramètres de contrôle et la mémoire tampon de données pour chaque transfert dans la séquence. La mémoire tampon est un objet WDFMEMORY qui, dans l’implémentation actuelle, encapsule un MDL chaîné. Pour plus d’informations sur les DLL chaînées, consultez Utilisation de MDLs.

Le contrôleur SPB doit conserver l’appareil cible sélectionné pour l’opération de séquence entière. Si la cible est sélectionnée par une ligne de sélection d’appareil, la ligne peut être déclarée en continu à partir du début du premier transfert dans la séquence jusqu’à la fin du dernier transfert. Cette ligne peut être déclarée aussi tôt que l’opération de verrouillage au début de la séquence et peut rester déclarée jusqu’à ce que l’opération de déverrouillage à la fin de la séquence.

Un délai facultatif peut être spécifié pour chaque transfert dans une séquence. Le pilote du contrôleur SPB est chargé de retarder au moins ce nombre de microsecondes avant de commencer le transfert. Si le premier transfert dans la séquence a un délai associé, le pilote doit d’abord transmettre l’adresse ou déclarer la ligne de sélection de périphérique de l’appareil cible, puis retarder l’heure spécifiée avant de commencer le transfert de données. Pendant ce délai, la cible doit rester sélectionnée, mais le contrôleur ne doit pas exécuter l’horloge sur le bus.

Si l’appareil cible signale un NACK pendant un transfert dans une séquence, le contrôleur SPB arrête la séquence. (Autrement dit, le contrôleur ne réessaye pas le transfert défaillant et n’essaie pas d’effectuer les transferts restants dans la séquence.) Si cela se produit, le pilote du contrôleur SPB doit définir l’état d’achèvement de la demande d’E/S sur STATUS_SUCCESS, définir le champ Informations dans le bloc d’état d’E/S sur le nombre d’octets réellement transférés (sans compter les données perdues dans le transfert reçu par le NACK) et terminer la requête.

Le pilote du contrôleur SPB doit terminer la demande d’E/S avec un code d’état d’erreur uniquement si l’une des conditions suivantes se produit :

Le contrôleur SPB ne peut pas sélectionner l’appareil cible (par exemple, un appareil cible sur un I²bus C signale un NACK lorsque le contrôleur transmet l’octet d’adresse).
Le pilote du contrôleur SPB obtient un état d’erreur à partir d’un appel à un service WDF ou WDM lors du traitement de l’opération de séquence.

Pour inscrire une fonction de rappel EvtSpbControllerIoSequence, appelez la méthode SpbDeviceInitialize.

Exemples

Pour définir une EvtSpbControllerIoSequence fonction de rappel, vous devez d’abord fournir une déclaration de fonction qui identifie le type de fonction de rappel que vous définissez. Windows fournit un ensemble de types de fonctions de rappel pour les pilotes. La déclaration d’une fonction à l’aide des types de fonctions de rappel permet d'Analyse du code pour les pilotes, static Driver Verifier (SDV) et d’autres outils de vérification recherchent des erreurs, et il est nécessaire d’écrire des pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une fonction de rappel EvtSpbControllerIoSequence nommée MyEvtSpbControllerIoSequence, utilisez le type de fonction EVT_SPB_CONTROLLER_SEQUENCE, comme illustré dans cet exemple de code :

EVT_SPB_CONTROLLER_SEQUENCE  MyEvtSpbControllerIoSequence;

Ensuite, implémentez votre fonction de rappel comme suit :

_Use_decl_annotations_
VOID
  MyEvtSpbControllerIoSequence(
    WDFDEVICE Controller,
    SPBTARGET Target,
    SPBREQUEST Request,
    ULONG TransferCount
    )
{ ... }

Le type de fonction EVT_SPB_CONTROLLER_SEQUENCE est défini dans le fichier d’en-tête Spbcx.h. Pour identifier plus précisément les erreurs lorsque vous exécutez les outils d’analyse du code, veillez à ajouter l’annotation Use_decl_annotations à votre définition de fonction. L’annotation Use_decl_annotations garantit que les annotations appliquées au type de fonction EVT_SPB_CONTROLLER_SEQUENCE dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes KMDF. Pour plus d’informations sur Use_decl_annotations, consultez annoter le comportement de la fonction.

Exigences

Exigence	Valeur
client minimum pris en charge	Prise en charge à partir de Windows 8.
plateforme cible	Bureau
d’en-tête	spbcx.h
IRQL	Appelé au <IRQL = DISPATCH_LEVEL.

Partager via