EVT_SERCX2_PIO_RECEIVE_READ_BUFFER fonction de rappel (sercx.h)

Article
10/30/2024

La fonction de rappel d’événements EvtSerCx2PioReceiveReadBuffer 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 des données du FIFO de réception dans le contrôleur série vers une mémoire tampon de lecture.

Syntaxe

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER EvtSercx2PioReceiveReadBuffer;

ULONG EvtSercx2PioReceiveReadBuffer(
  [in]  SERCX2PIORECEIVE PioReceive,
  [out] PUCHAR Buffer,
  [in]  ULONG Length
)
{...}

Paramètres

[in] PioReceive

Handle SERCX2PIORECEIVE à un objet de réception d’authentification unique. Le pilote du contrôleur série a précédemment appelé la méthode SerCx2PioReceiveCreate pour créer cet objet.

[out] Buffer

Pointeur vers la mémoire tampon de lecture. 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 de lecture qui sont disponibles pour stocker les données reçues.

Valeur de retour

La fonction EvtSerCx2PioReceiveReadBuffer retourne le nombre d’octets de données qu’elle a correctement transférées de la fiFO de réception dans le matériel du contrôleur série vers la mémoire tampon de lecture.

Remarques

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

SerCx2 peut appeler la fonction EvtSerCx2PioReceiveReadBuffer plusieurs fois pendant une transaction de réception PIO. Un seul appel EvtSerCx2PioReceiveReadBuffer suffit si cet appel peut remplir la mémoire tampon de lecture avec les données du FIFO de réception. Sinon, SerCx2 continue d’appeler cette fonction, à mesure que d’autres données deviennent disponibles dans la fiFO de réception, jusqu’à ce que la mémoire tampon de lecture soit remplie.

La fonction EvtSerCx2PioReceiveReadBuffer utilise l’authentification pio pour transférer autant d’octets que possible du FIFO de réception vers la mémoire tampon de lecture. La fonction continue de transférer des données à partir du FIFO tant que la mémoire tampon passée à cette fonction n’est pas complète et que le registre d’état de ligne (LSR) indique que d’autres données sont disponibles à partir du FIFO. Si le LSR indique que le FIFO est vide, la fonction retourne sans remplir la mémoire tampon. Sinon, la fonction remplit 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 avec succès vers la mémoire tampon de lecture à partir du FIFO de réception.

En règle générale, la fonction EvtSerCx2PioReceiveReadBuffer n’active aucune interruption. Au lieu de cela, si la fiFO de réception s’exécute en dehors des données avant que la fonction puisse remplir la mémoire tampon de lecture, SerCx2 appelle l'EvtSerCx2PioReceiveEnableReadyNotification fonction de rappel d’événement pour activer une notification prête, et cette fonction active une interruption qui se produit lorsque plus de données sont disponibles dans la fonction FIFO de réception.

Pour chaque appel successif à la fonction EvtSerCx2PioReceiveReadBuffer, SerCx2 ajuste tampon pour pointer vers la région de mémoire tampon suivante à remplir et définit Longueur sur le nombre d’octets d’espace non rempli qui restent dans la mémoire tampon.

La notification prête n’est jamais activée lorsque SerCx2 appelle la fonction EvtSerCx2PioReceiveEnableReadyNotification. Toutefois, SerCx2 peut appeler cette fonction à partir du même thread à partir duquel le pilote a appelé la méthode SerCx2PioReceiveReady.

Si le pilote implémente une fonction EvtSerCx2PioReceiveInitializeTransaction, SerCx2 appelle cette fonction au début d’une transaction de transmission PIO, avant le premier appel à la fonction EvtSerCx2PioReceiveReadBuffer. Si le pilote implémente une fonction EvtSerCx2PioReceiveCleanupTransaction, SerCx2 appelle cette fonction à la fin d’une transaction PIO-receive, après l’appel final à la fonction EvtSerCx2PioReceiveReadBuffer.

En plus d’appeler la fonction EvtSerCx2PioReceiveReadBuffer pendant les transactions pio-receive, SerCx2 appelle cette fonction pour enregistrer l’état de la réception FIFO juste avant que le contrôleur série quitte l’état d’alimentation de l’appareil D0. Pour plus d’informations, consultez SerCx2SaveReceiveFifoOnD0Exit.

Pour plus d’informations sur les transactions de réception d’authentification personnelle, consultez SerCx2 PIO-Receive Transactions.

Exemples

Pour définir une EvtSerCx2PioReceiveReadBuffer 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 EvtSerCx2PioReceiveReadBuffer nommée MyPioReceiveReadBuffer, utilisez le type de fonction EVT_SERCX2_PIO_RECEIVE_READ_BUFFER, comme illustré dans cet exemple de code :

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER  MyPioReceiveReadBuffer;

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

_Use_decl_annotations_
ULONG
  MyPioReceiveReadBuffer(
    SERCX2PIORECEIVE  PioReceive,
    PUCHAR  Buffer,
    ULONG  Length

    )
  {...}

Le type de fonction EVT_SERCX2_PIO_RECEIVE_READ_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_RECEIVE_READ_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.