Partager via

SerCx2 Custom-Receive Transactions

  • Article

Certains matériels de contrôleur série peuvent implémenter un mécanisme de transfert de données autre que PIO ou DMA système pour lire les données à partir d’un contrôleur série. Un pilote de contrôleur série peut prendre en charge les transactions de réception personnalisées pour rendre ce mécanisme de transfert de données disponible pour être utilisé par SerCx2.

Pour démarrer une transaction de réception personnalisée, SerCx2 appelle la fonction de rappel d’événement EvtSerCx2CustomReceiveTransactionStart du pilote et fournit en tant que paramètres la demande de lecture (IRP_MJ_READ) et une description de la mémoire tampon de lecture pour la transaction. Dans cet appel, la fonction lance la transaction et retourne. Le pilote est ensuite responsable de la fin de la transaction et de la fin de la demande de lecture.

Création de l’objet de réception personnalisé

Avant que SerCx2 puisse appeler l’une des fonctions EvtSerCx2CustomReceiveTransactionXxx** du pilote série, le pilote doit appeler la méthode SerCx2CustomReceiveTransactionCreate pour inscrire ces fonctions auprès de SerCx2. Cette méthode accepte, en tant que paramètre d’entrée, un pointeur vers une structure SERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG qui contient des pointeurs vers les fonctions EvtSerCx2CustomReceiveTransactionXxx** du pilote.

Le pilote doit implémenter les deux fonctions suivantes :

En option, le pilote peut implémenter l’une ou l’ensemble des trois fonctions suivantes :

La méthode SerCx2CustomReceiveTransactionCreate crée un objet de réception personnalisé et fournit au pilote appelant un handle SERCX2CUSTOMRECEIVETRANSACTION pour cet objet. Les fonctions EvtSerCx2CustomReceiveTransactionXxx** du pilote prennent toutes ce handle comme premier paramètre. Les méthodes SerCx2 suivantes prennent ce handle comme premier paramètre :

Initialisation matérielle et propre-up

Certains pilotes de contrôleur série peuvent avoir besoin d’initialiser le matériel du contrôleur série au début d’une transaction de réception personnalisée ou de propre l’état matériel du contrôleur série à la fin de la transaction.

Si un pilote implémente une fonction de rappel d’événement EvtSerCx2CustomReceiveTransactionInitialize , SerCx2 appelle cette fonction pour initialiser le contrôleur série avant de démarrer la transaction. Si elle est implémentée, la fonction EvtSerCx2CustomReceiveTransactionInitialize doit appeler la méthode SerCx2CustomReceiveTransactionInitializeComplete pour informer SerCx2 lorsque le pilote termine l’initialisation du contrôleur série.

Si le pilote implémente une fonction de rappel d’événement EvtSerCx2CustomReceiveTransactionCleanup, SerCx2 appelle cette fonction pour propre l’état matériel une fois la transaction terminée. Si elle est implémentée, la fonction EvtSerCx2CustomReceiveTransactionInitialize doit appeler la méthode SerCx2CustomReceiveTransactionCleanupComplete pour informer SerCx2 lorsque le pilote termine le nettoyage du contrôleur série.

Notifications de nouvelles données

En option, le pilote de contrôleur série peut implémenter une fonction de rappel d’événement EvtSerCx2CustomReceiveTransactionEnableNewDataNotification . S’il est implémenté, SerCx2 utilise cette fonction pour gérer efficacement les délais d’attente qui se produisent pendant la gestion des demandes de lecture qui sont traitées en tant que transactions de réception personnalisées.

Un délai d’expiration d’intervalle se produit si l’intervalle entre deux octets successifs reçus par le contrôleur série dépasse une durée maximale spécifiée par le client. Une fois qu’un pilote de périphérique a envoyé une demande de lecture à SerCx2, un délai d’expiration d’intervalle ne peut se produire qu’après la réception d’au moins un octet de données à partir du périphérique connecté en série. Le délai entre l’arrivée d’une demande de lecture et la réception du premier octet de données à partir de l’appareil périphérique peut être considérablement plus long que le temps nécessaire pour recevoir le reste des données pour la demande de lecture après la réception du premier octet. Pour plus d’informations, consultez SERIAL_TIMEOUTS.

SerCx2 appelle la fonction EvtSerCx2CustomReceiveTransactionEnableNewDataNotification , si elle est implémentée, pour activer une notification de nouvelles données. Si cette notification est activée et que le contrôleur série reçoit un ou plusieurs octets de nouvelles données de l’appareil périphérique, ou qu’il contient déjà des données dans son FIFO de réception, le pilote du contrôleur série doit appeler la méthode SerCx2CustomReceiveTransactionNewDataNotification pour notifier SerCx2.

Pour détecter un délai d’expiration d’intervalle possible, SerCx2 appelle régulièrement la fonction de rappel d’événement EvtSerCx2CustomReceiveTransactionQueryProgress pour case activée si des données ont été reçues au cours de l’intervalle précédent. La façon dont SerCx2 détecte la réception du premier octet de données dépend si le pilote de contrôleur série implémente une fonction EvtSerCx2CustomReceiveTransactionEnableNewDataNotification . Si cette fonction est implémentée, SerCx2 appelle la fonction pour activer une notification de nouvelles données et est averti par le pilote lors de la réception du premier octet de données. Sinon, SerCx2 appelle régulièrement la fonction EvtSerCx2CustomReceiveTransactionQueryProgress pour détecter la réception du premier octet et peut avoir besoin de réveiller régulièrement le processeur pour effectuer ces appels. Ainsi, un pilote qui implémente une fonction EvtSerCx2CustomReceiveTransactionEnableNewDataNotification peut réduire la consommation d’énergie en n’obligeant pas le processeur à se réveiller aussi souvent.

SerCx2 n’annule pas explicitement une notification de nouvelles données en attente pour une transaction de réception personnalisée. Toutefois, le pilote de contrôleur série peut avoir besoin d’annuler implicitement une notification de nouvelles données si la notification est activée et si le pilote doit terminer la demande de lecture associée pour l’une des raisons suivantes :

  • La demande de lecture expire ou est annulée.
  • Le contrôleur série est sur le point de quitter l’état d’alimentation de l’appareil D0 pour entrer dans un état d’alimentation faible.

Le pilote appelle généralement une méthode telle que WdfRequestComplete pour terminer la demande. Le pilote ne doit jamais appeler SerCx2CustomReceiveTransactionNewDataNotification une fois la demande terminée.

Accès à l’objet de requête

Pour démarrer une transaction de réception personnalisée, SerCx2 appelle la fonction EvtSerCx2CustomReceiveTransactionStart du pilote et transmet la demande de lecture associée (encapsulée dans un handle d’objet WDFREQUEST) à cette fonction en tant que paramètre. Le pilote est responsable de l’appel d’une méthode telle que WdfRequestComplete pour effectuer cette demande une fois la transaction terminée. À moins que la demande ne puisse être effectuée immédiatement, avant que la fonction EvtSerCx2CustomReceiveTransactionStart ne retourne, le pilote doit appeler une méthode telle que WdfRequestMarkCancelableEx pour marquer la demande comme annulable.

Le pilote de contrôleur série ne doit pas utiliser une méthode telle que WdfRequestRetrieveOutputBuffer pour accéder à la mémoire tampon de données dans la demande de lecture. Au lieu de cela, le pilote doit utiliser les valeurs des paramètres Mdl, Offset et Length passées à la fonction EvtSerCx2CustomReceiveTransactionStart pour accéder à cette mémoire tampon.

Lors d’une transaction de réception personnalisée, le pilote peut avoir besoin de stocker des informations sur la transaction dans un contexte attaché à l’objet de requête. Si c’est le cas, la fonction de rappel d’événement EvtDriverDeviceAdd du pilote peut appeler la méthode WdfDeviceInitSetRequestAttributes pour définir les attributs à utiliser pour les objets de requête. Ces attributs incluent le nom et la taille d’allocation à utiliser pour les contextes de requête. Les attributs de requête spécifiés dans cet appel doivent correspondre aux attributs de requête que le pilote spécifie dans l’appel à la méthode SerCx2InitializeDevice . Ces attributs sont spécifiés dans le membre RequestAttributes de la structure SERCX2_CONFIG que le pilote transmet à SerCx2InitializeDevice. Pour plus d’informations, consultez SERCX2_CONFIG.

Pour une demande de lecture que le pilote de contrôleur série reçoit au début d’une transaction de réception personnalisée, le contexte de requête alloué par l’infrastructure de pilote n’est pas initialisé. Le pilote doit, comme bonne pratique, appeler la routine RtlZeroMemory pour initialiser ce contexte de requête à tous les zéros.