EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER fonction de rappel (sercx.h)

Article
02/26/2024

La fonction de rappel d’événement EvtSerCx2PioTransmitWriteBuffer est appelée par la version 2 de l’extension d’infrastructure série (SerCx2) pour utiliser les E/S programmées (PIO) pour transférer le contenu d’une mémoire tampon d’écriture vers le FIFO de transmission dans le contrôleur série.

Syntaxe

EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER EvtSercx2PioTransmitWriteBuffer;

ULONG EvtSercx2PioTransmitWriteBuffer(
  [in] SERCX2PIOTRANSMIT PioTransmit,
  [in] PUCHAR Buffer,
  [in] ULONG Length
)
{...}

Paramètres

[in] PioTransmit

Handle SERCX2PIOTRANSMIT à un objet de transmission PIO. Le pilote du contrôleur série a précédemment appelé la méthode SerCx2PioTransmitCreate pour créer cet objet.

[in] Buffer

Pointeur vers la mémoire tampon d’écriture. Ce paramètre est l’adresse virtuelle d’une mémoire tampon verrouillée dans la mémoire système.

[in] Length

Nombre d’octets dans la mémoire tampon d’écriture qui peuvent être transmis.

Valeur retournée

La fonction EvtSerCx2PioTransmitWriteBuffer retourne le nombre d’octets de données qu’elle a correctement transférées de la mémoire tampon d’écriture vers le fichier FIFO de transmission dans le matériel du contrôleur série.

Remarques

Votre pilote de contrôleur série doit implémenter cette fonction. Le pilote inscrit la fonction dans l’appel SerCx2PioTransmitCreate qui crée l’objet de transmission PIO.

SerCx2 peut appeler la fonction EvtSerCx2PioTransmitWriteBuffer plusieurs fois pendant une transaction de transmission PIO. Un seul appel EvtSerCx2PioTransmitWriteBuffer suffit si cet appel peut transférer le contenu complet de la mémoire tampon d’écriture vers le FIFO de transmission. Sinon, SerCx2 continue d’appeler cette fonction, car plus d’espace est disponible dans le fichier FIFO de transmission, jusqu’à ce que la mémoire tampon d’écriture soit vidée.

À compter du premier octet de la mémoire tampon d’écriture, la fonction EvtSerCx2PioTransmitWriteBuffer utilise PIO pour transférer autant d’octets que possible de la mémoire tampon vers le FIFO de transmission. La fonction continue de transférer des données à partir de la mémoire tampon tant que la mémoire tampon n’est pas vide et que la ligne status registre (LSR) indique que le FIFO peut accepter davantage de données. Si la LSR indique que le FIFO ne peut accepter plus de données, la fonction retourne sans vider la mémoire tampon. Sinon, la fonction transfère tous les octets de la mémoire tampon et retourne. Dans les deux cas, la valeur retournée par cette fonction est le nombre d’octets de données qui ont été correctement transférés de la mémoire tampon d’écriture vers le fichier FIFO de transmission.

En règle générale, la fonction EvtSerCx2PioTransmitWriteBuffer n’active aucune interruption. Au lieu de cela, si la fonction ne peut pas transférer l’intégralité du contenu de la mémoire tampon d’écriture vers le FIFO de transmission, SerCx2 appelle la fonction de rappel d’événement EvtSerCx2PioTransmitEnableReadyNotification pour activer une notification prête, et cette fonction active une interruption qui se produit lorsque la transmission fiFO devient vide.

Pour chaque appel successif à la fonction EvtSerCx2PioTransmitWriteBuffer , SerCx2 ajuste Buffer de façon à pointer vers les données restantes dans la mémoire tampon, et définit Length sur le nombre d’octets de données qui restent dans la mémoire tampon.

La notification ready n’est jamais activée lorsque SerCx2 appelle la fonction EvtSerCx2PioTransmitEnableReadyNotification . Toutefois, SerCx2 peut appeler cette fonction à partir du thread à partir duquel le pilote a appelé la méthode SerCx2PioTransmitReady .

Si le pilote implémente une fonction EvtSerCx2PioTransmitInitializeTransaction , SerCx2 appelle cette fonction au début d’une transaction PIO-transmit, avant le premier appel à la fonction EvtSerCx2PioTransmitWriteBuffer . Si le pilote implémente une fonction EvtSerCx2PioTransmitCleanupTransaction , SerCx2 appelle cette fonction à la fin d’une transaction piO-transmit, après le dernier appel EvtSerCx2PioTransmitWriteBuffer et après tout appel aux fonctions EvtSerCx2PioTransmitDrainFifo, EvtSerCx2PioTransmitCancelDrainFifo et EvtSerCx2PioTransmitPurgeFifo , si elles sont implémentées.

Pour plus d’informations sur les transactions de transmission piO, consultez Transactions SerCx2 PIO-Transmit.

Exemples

Pour définir une fonction de rappel EvtSerCx2PioTransmitWriteBuffer , 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 EvtSerCx2PioTransmitWriteBuffer nommée MyPioTransmitWriteBuffer, utilisez le type de fonction EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER , comme indiqué dans cet exemple de code :

EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER  MyPioTransmitWriteBuffer;

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

_Use_decl_annotations_
ULONG
  MyPioTransmitWriteBuffer(
    SERCX2PIOTRANSMIT  PioTransmit,
    PUCHAR Buffer,
    ULONG Length
    )
  {...}

Le type de fonction EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER est défini dans le fichier d’en-tête Sercx.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_SERCX2_PIO_TRANSMIT_WRITE_BUFFER 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	Disponible à partir de Windows 8.1.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	sercx.h
IRQL	Appelé à IRQL <= DISPATCH_LEVEL.