EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER fonction de rappel (sercx.h)

Article
10/30/2024

La fonction de rappel d’événement EvtSerCx2PioTransmitWriteBuffer est appelée par la version 2 de l’extension de framework série (SerCx2) pour utiliser l’authentification unique programmée (PIO) pour transférer le contenu d’une mémoire tampon d’écriture vers la transmission fiFO 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 sont disponibles pour être transmis.

Valeur de retour

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 la 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 la transmission FIFO. Sinon, SerCx2 continue d’appeler cette fonction, car plus d’espace devient disponible dans la 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 l’authentification personnelle pour transférer autant d’octets que possible de la mémoire tampon vers la fonction 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 le registre d’état de ligne (LSR) indique que le FIFO peut accepter davantage de données. Si le 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é transférés à partir de la mémoire tampon d’écriture vers la transmission FIFO.

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 la fonction FIFO de transmission, SerCx2 appelle l'EvtSerCx2PioTransmitEnableReadyNotification fonction de rappel d’événement 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 tampon pour pointer vers les données restantes dans la mémoire tampon et définit Longueur sur le nombre d’octets de données qui restent dans la mémoire tampon.

La notification prête n’est jamais activée lorsque SerCx2 appelle la fonction EvtSerCx2PioTransmitEnableReadyNotification. Toutefois, SerCx2 peut appeler cette fonction à partir du même 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 de transmission PIO, avant le premier appel à la fonction evtSerCx2PioTransmitWriteBuffer. Si le pilote implémente une fonction EvtSerCx2PioTransmitCleanupTransaction, SerCx2 appelle cette fonction à la fin d’une transaction de transmission PIO, après la dernière EvtSerCx2PioTransmitWriteBuffer appel, et après tout appel à l'EvtSerCx2PioTransmitDrainFifo, EvtSerCx2PioTransmitCancelDrainFifoet EvtSerCx2PioTransmitPurgeFifo fonctions, si elles sont implémentées.

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

Exemples

Pour définir une EvtSerCx2PioTransmitWriteBuffer 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 EvtSerCx2PioTransmitWriteBuffer nommée MyPioTransmitWriteBuffer, utilisez le type de fonction EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER, comme illustré 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 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_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 annoter le comportement de la fonction.