EVT_SERCX2_PIO_RECEIVE_READ_BUFFER fonction de rappel (sercx.h)

Article
02/27/2024

La fonction de rappel d’événement EvtSerCx2PioReceiveReadBuffer 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 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 piO-receive. Le pilote de 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 disponibles pour stocker les données reçues.

Valeur retournée

La fonction EvtSerCx2PioReceiveReadBuffer retourne le nombre d’octets de données qu’elle a correctement transférées du fichier 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 PIO-receive.

SerCx2 peut appeler la fonction EvtSerCx2PioReceiveReadBuffer plusieurs fois au cours d’une transaction PIO-receive. 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 davantage de données sont disponibles dans le fichier FIFO de réception, jusqu’à ce que la mémoire tampon de lecture soit remplie.

La fonction EvtSerCx2PioReceiveReadBuffer utilise 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 saturée et que la ligne status registre (LSR) indique que davantage de données sont disponibles à partir du FIFO. Si la LSR indique que le fichier 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é correctement transféré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 fonction FIFO de réception est à court de données avant que la fonction puisse remplir la mémoire tampon de lecture, SerCx2 appelle la fonction de rappel d’événement EvtSerCx2PioReceiveEnableReadyNotification pour activer une notification prête, et cette fonction active une interruption qui se produit lorsque davantage de données sont disponibles dans la réception FIFO.

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

La notification ready n’est jamais activée lorsque SerCx2 appelle la fonction EvtSerCx2PioReceiveEnableReadyNotification . Toutefois, SerCx2 peut appeler cette fonction à partir du 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 PIO-transmit, 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 du FIFO de réception juste avant que le contrôleur série ne quitte l’état d’alimentation de l’appareil D0. Pour plus d’informations, consultez SerCx2SaveReceiveFifoOnD0Exit.

Pour plus d’informations sur les transactions PIO-receive, consultez SerCx2 PIO-Receive Transactions.

Exemples

Pour définir une fonction de rappel EvtSerCx2PioReceiveReadBuffer , 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 EvtSerCx2PioReceiveReadBuffer nommée MyPioReceiveReadBuffer, utilisez le type de fonction EVT_SERCX2_PIO_RECEIVE_READ_BUFFER , comme indiqué 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 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_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 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.