EVT_SPB_CONTROLLER_SEQUENCE fonction de rappel (spbcx.h)

Article
08/07/2023

La fonction de rappel d’événement EvtSpbControllerIoSequence d’un 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 demande 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

Un handle WDFDEVICE pour l’objet d’appareil d’infrastructure qui représente le contrôleur SPB.

[in] Target

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

[in] Request

Handle SPBREQUEST pour la demande d’E/S. Votre pilote de contrôleur SPB doit effectuer cette demande en effectuant l’opération demandée ou en retournant une erreur status. 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

None

Remarques

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

Un rappel EvtSpbControllerIoSequence ne retourne pas de valeur status. Au lieu de cela, le pilote du contrôleur SPB indique la status de l’opération de séquence dans le status d’achèvement pour 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 la fin de l’opération. Plus tard, le pilote du contrôleur SPB continue de traiter la demande ou la termine pendant les DPC d’interruption ou les DCP du minuteur.

Le pilote de contrôleur SPB peut récupérer les valeurs de paramètres de la demande 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 de 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 une MDL chaînée. Pour plus d’informations sur les DLL chaînées, consultez Utilisation de MDL.

Le contrôleur SPB doit conserver l’appareil cible sélectionné pour l’ensemble de l’opération de séquence. 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 de la séquence jusqu’à la fin du dernier transfert. Cette ligne peut être déclarée dès l’opération de verrouillage au début de la séquence et peut rester déclarée jusqu’à 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 de la séquence a un délai associé, le pilote doit d’abord transmettre l’adresse ou affirmer la ligne de sélection du périphérique de l’appareil cible, puis retarder pendant la durée 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 retentera 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 la status d’achèvement de la demande d’E/S sur STATUS_SUCCESS, définir le champ Informations dans le bloc d’E/S status sur le nombre d’octets effectivement transférés (sans compter les données perdues dans le transfert qui a reçu le NACK) et terminer la demande.

Le pilote du contrôleur SPB doit terminer la demande d’E/S avec une erreur status code 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 bus I²C signale un NACK quand le contrôleur transmet l’octet d’adresse).
Le pilote du contrôleur SPB obtient une erreur status 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 fonction de rappel EvtSpbControllerIoSequence , 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 fonction de rappel permet à l’analyse du code pour les pilotes, au vérificateur de pilotes statiques (SDV) et à d’autres outils de vérification de trouver des erreurs. Il s’agit d’une exigence pour l’écriture de 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 lors de l’exécution des 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 Annotating Function Behavior.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Pris en charge à partir de Windows 8.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	spbcx.h
IRQL	Appelé à IRQL <= DISPATCH_LEVEL.

Partager via