SerCx2 Custom-Transmit Transactions
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 écrire des données dans un contrôleur série. Un pilote de contrôleur série peut prendre en charge les transactions de transmission personnalisée pour rendre ce mécanisme de transfert de données disponible pour être utilisé par SerCx2.
Pour démarrer une transaction de transmission personnalisée, SerCx2 appelle la fonction de rappel d’événement EvtSerCx2CustomTransmitTransactionStart du pilote et fournit en tant que paramètres la demande d’écriture (IRP_MJ_WRITE) et une description de la mémoire tampon d’écriture pour la transaction. Dans cet appel, la fonction lance la transaction et retourne. Le pilote est ensuite chargé de terminer la transaction et de terminer la demande d’écriture.
Création de l’objet de transmission personnalisée
Avant que SerCx2 puisse appeler les fonctions EvtSerCx2CustomTransmitTransactionXxx**, le pilote doit appeler la méthode SerCx2CustomTransmitTransactionCreate 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_TRANSMIT_TRANSACTION_CONFIG qui contient des pointeurs vers les fonctions EvtSerCx2CustomTransmitTransmitTransactionXxx** du pilote.
Le pilote doit implémenter la fonction suivante :
En option, le pilote peut implémenter l’une des fonctions suivantes ou les deux :
La méthode SerCx2CustomTransmitTransactionCreate crée un objet de transmission personnalisée et fournit au pilote appelant un handle SERCX2CUSTOMTRANSMITTRANSACTION à cet objet. Les fonctions EvtSerCx2CustomTransmitTransactionXxx** 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 transmission 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 EvtSerCx2CustomTransmitTransactionInitialize , 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 EvtSerCx2CustomTransmitTransactionInitialize doit appeler la méthode SerCx2CustomTransmitTransactionInitializeComplete 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 EvtSerCx2CustomTransmitTransactionCleanup, SerCx2 appelle cette fonction pour propre l’état matériel à la fin de la transaction. Si elle est implémentée, la fonction EvtSerCx2CustomTransmitTransactionInitialize doit appeler la méthode SerCx2CustomTransmitTransactionCleanupComplete pour informer SerCx2 lorsque le pilote termine le nettoyage du contrôleur série.
Accès à l’objet de requête
Pour démarrer une transaction de transmission personnalisée, SerCx2 appelle la fonction EvtSerCx2CustomTransmitTransactionStart du pilote et transmet la demande d’écriture associée (encapsulée dans un handle d’objet WDFREQUEST) à cette fonction en tant que paramètre. Le pilote est chargé d’appeler une méthode telle que WdfRequestComplete pour terminer cette requête lorsque la transaction est terminée. À moins que la requête ne puisse être effectuée immédiatement, avant que la fonction EvtSerCx2CustomTransmitTransactionStart ne retourne, le pilote doit appeler une méthode telle que WdfRequestMarkCancelableEx pour marquer la demande comme annulable.
Le pilote du contrôleur série ne doit pas utiliser une méthode telle que WdfRequestRetrieveInputBuffer pour accéder à la mémoire tampon de données dans la demande d’écriture. Au lieu de cela, le pilote doit utiliser les valeurs des paramètres Mdl, Offset et Length passées à la fonction EvtSerCx2CustomTransmitTransactionStart pour accéder à cette mémoire tampon.
Pendant une transaction de transmission personnalisée, le pilote peut avoir besoin de stocker des informations sur la transaction dans un contexte attaché à l’objet de requête. Dans ce 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 spécifiés par le pilote 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 d’écriture que le pilote du contrôleur série reçoit au début d’une transaction de transmission personnalisée, le contexte de requête alloué par l’infrastructure de pilote n’est pas initialisé. Le pilote doit, à titre de bonne pratique, appeler la routine RtlZeroMemory pour initialiser ce contexte de requête sur tous les zéros.