EVT_SERCX2_SELECT_NEXT_RECEIVE_TRANSACTION_TYPE fonction de rappel (sercx.h)

Article
02/26/2024

La fonction de rappel d’événement EvtSerCx2SelectNextReceiveTransactionType 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 de lecture suivante.

Syntaxe

EVT_SERCX2_SELECT_NEXT_RECEIVE_TRANSACTION_TYPE EvtSercx2SelectNextReceiveTransactionType;

SERCX2_TRANSACTION_TYPE EvtSercx2SelectNextReceiveTransactionType(
  [in]  WDFDEVICE Device,
  [in]  PMDL Mdl,
  [in]  ULONG Offset,
  [in]  ULONG RemainingLength,
  [out] SERCX2CUSTOMRECEIVE *CustomReceive,
  [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 de lecture pour la prochaine transaction de réception. 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 de lecture (IRP_MJ_READ) 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] CustomReceive

Pointeur vers un emplacement dans lequel la fonction écrit le SERCX2CUSTOMRECEIVE handle dans l’objet custom-receive. Si la fonction retourne 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 SerCx2CustomReceiveCreate . 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 prochaine transaction de réception. Si la valeur de retour est SerCx2TransactionTypeDefault, cette valeur de sortie est ignorée par SerCx2.

Valeur retournée

La fonction EvtSerCx2SelectNextReceiveTransactionType 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ées) ou pour laisser SerCx2 choisir le type de transaction à utiliser pour la prochaine transaction de réception.

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 EvtSerCx2SelectNextReceiveTransactionType , SerCx2 décide toujours du type de mécanisme de transfert de données (PIO, DMA système ou personnalisé) à utiliser pour la prochaine transaction de réception. 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 system-DMA-receive fournit une structure SERCX2_SYSTEM_DMA_RECEIVE_CONFIG qui contient ces informations. Un pilote qui prend en charge les transactions de réception personnalisées fournit une structure SERCX2_CUSTOM_RECEIVE_CONFIG qui contient ces informations.

Si votre pilote de contrôleur série implémente une fonction EvtSerCx2SelectNextReceiveTransactionType , 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 réception. 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_RECEIVE_CONFIG .

Note Même si un pilote de contrôleur série implémente une fonction EvtSerCx2SelectNextReceiveTransactionType , SerCx2 utilise des transactions piO-receive 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 EvtSerCx2CustomReceiveSelectNextTransactionType , 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 EvtSerCx2CustomReceiveSelectNextTransactionType nommée MyCustomReceiveSelectNextTransactionType, utilisez le type de fonction EVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE , comme indiqué dans cet exemple de code :

EVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE  MyCustomReceiveTransactionStart;

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

_Use_decl_annotations_
SERCX2_TRANSACTION_TYPE
  EvtSerCx2SelectNextReceiveTransactionType(
    WDFDEVICE  Device,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  RemainingLength,
    SERCX2CUSTOMRECEIVE  *CustomReceive,
    PULONG  NextTransactionLength
    )
  {...}

Le type de fonction EVT_SERCX2_CUSTOM_RECEIVE_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_RECEIVE_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.