EVT_SERCX2_SELECT_NEXT_TRANSMIT_TRANSACTION_TYPE fonction de rappel (sercx.h)

Article
08/07/2023

La fonction de rappel d’événement EvtSerCx2SelectNextTransmitTransactionType est appelée par la version 2 de l’extension d’infrastructure série (SerCx2) pour déterminer le mécanisme de transfert de données à utiliser pour l’opération d’écriture suivante.

Syntaxe

EVT_SERCX2_SELECT_NEXT_TRANSMIT_TRANSACTION_TYPE EvtSercx2SelectNextTransmitTransactionType;

SERCX2_TRANSACTION_TYPE EvtSercx2SelectNextTransmitTransactionType(
  [in]  WDFDEVICE Device,
  [in]  PMDL Mdl,
  [in]  ULONG Offset,
  [in]  ULONG RemainingLength,
  [out] SERCX2CUSTOMTRANSMIT *CustomTransmit,
  [out] PULONG NextTransactionLength
)
{...}

Paramètres

[in] Device

Un handle WDFDEVICE pour l’objet d’appareil framework qui représente le contrôleur série. Le pilote du contrôleur série a créé cet objet dans sa fonction de rappel EvtDriverDeviceAdd . Pour plus d’informations, consultez SerCx2InitializeDevice.

[in] Mdl

Pointeur vers une MDL qui décrit les pages mémoire qui sont couvertes par la mémoire tampon d’écriture pour la transaction de transmission suivante. La liste de points/regroupements pour le transfert DMA utilise la région de cette mémoire spécifiée par les paramètres Offset et Length .

[in] Offset

Décalage de départ pour le transfert de données suivant. Ce paramètre est un décalage d’octets à partir du début de la région de mémoire tampon décrite par la MDL. Si la MDL spécifie un total de N octets d’espace de mémoire tampon, les valeurs possibles de Décalage sont comprises entre 0 et N–1.

[in] RemainingLength

Nombre total d’octets de données qui restent à transférer dans la demande d’écriture (IRP_MJ_WRITE) actuelle. Si la MDL spécifie un total de N octets d’espace de mémoire tampon, les valeurs possibles de Length sont comprises entre 1 et N-Offset.

[out] CustomTransmit

Pointeur vers un emplacement dans lequel la fonction écrit le handle SERCX2CUSTOMTRANSMIT dans l’objet de transmission personnalisée. Si la fonction renvoie SerCx2TransactionTypeCustom, la fonction doit fournir le handle d’objet que le pilote de contrôleur série a créé lors d’un appel précédent à la méthode SerCx2CustomTransmitCreate . Si la valeur de retour n’est pas SerCx2TransactionTypeCustom, cette valeur de sortie est ignorée par SerCx2.

[out] NextTransactionLength

Pointeur vers un emplacement vers lequel la fonction écrit le nombre d’octets à transférer dans la transaction de transmission suivante. Si la valeur de retour est SerCx2TransactionTypeDefault, cette valeur de sortie est ignorée par SerCx2.

Valeur retournée

La fonction EvtSerCx2SelectNextTransmitTransactionType retourne une constante d’énumération SERCX2_TRANSACTION_TYPE pour indiquer s’il faut utiliser un type de transaction sélectionné par le pilote (E/S programmées, DMA système ou transfert de données personnalisé) ou pour laisser SerCx2 choisir le type de transaction à utiliser pour la prochaine transaction de transmission.

Remarques

Votre pilote de contrôleur série peut, en option, implémenter cette fonction. S’il est implémenté, le pilote inscrit cette fonction dans l’appel à la méthode SerCx2InitializeDevice qui termine l’initialisation de l’objet d’appareil framework pour le contrôleur série.

Si votre pilote de contrôleur série n’implémente pas de fonction EvtSerCx2SelectNextTransmitTransactionType , SerCx2 décide toujours du type de mécanisme de transfert de données (PIO, DMA système ou personnalisé) à utiliser pour la transaction de transmission suivante. SerCx2 base ses décisions sur les informations de configuration d’E/S fournies par le pilote de contrôleur série. Un pilote qui prend en charge les transactions de transmission système DMA fournit une structure SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG qui contient ces informations. Un pilote qui prend en charge les transactions de transmission personnalisée fournit une structure SERCX2_CUSTOM_TRANSMIT_CONFIG qui contient ces informations.

Si votre pilote de contrôleur série implémente une fonction EvtSerCx2SelectNextTransmitTransactionType , SerCx2 appelle cette fonction pour déterminer le type de mécanisme de transfert de données (PIO, DMA système ou personnalisé) à utiliser pour la prochaine transaction de transmission. Vous pouvez implémenter cette fonction si le contrôleur série a des fonctionnalités matérielles spéciales qui ne peuvent pas être décrites correctement par les informations de configuration d’E/S dans les structures SERCX2_XXX_TRANSMIT_CONFIG .

Note Même si un pilote de contrôleur série implémente une fonction EvtSerCx2SelectNextTransmitTransactionType , SerCx2 utilise des transactions de transmission PIO pour effectuer certains types de transferts de données sans appeler d’abord cette fonction.

Pour plus d’informations, consultez Vue d’ensemble des transactions D/S SerCx2.

Exemples

Pour définir une fonction de rappel EvtSerCx2CustomTransmitSelectNextTransactionType , 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 EvtSerCx2CustomTransmitSelectNextTransactionType nommée MyCustomTransmitSelectNextTransactionType, utilisez le type de fonction EVT_SERCX2_CUSTOM_TRANSMIT_SELECT_NEXT_TRANSACTION_TYPE , comme indiqué dans cet exemple de code :

EVT_SERCX2_CUSTOM_TRANSMIT_SELECT_NEXT_TRANSACTION_TYPE  MyCustomTransmitTransactionStart;

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

_Use_decl_annotations_
SERCX2_TRANSACTION_TYPE
  EvtSerCx2SelectNextTransmitTransactionType(
    WDFDEVICE  Device,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  RemainingLength,
    SERCX2CUSTOMTRANSMIT  *CustomTransmit,
    PULONG  NextTransactionLength
    )
  {...}

Le type de fonction EVT_SERCX2_CUSTOM_TRANSMIT_SELECT_NEXT_TRANSACTION_TYPE 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_CUSTOM_TRANSMIT_SELECT_NEXT_TRANSACTION_TYPE 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.