WDF_USB_CONTINUOUS_READER_CONFIG structure (wdfusb.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La structure WDF_USB_CONTINUOUS_READER_CONFIG contient des informations que l’infrastructure utilise pour configurer un lecteur continu pour un canal USB.

Syntaxe

typedef struct _WDF_USB_CONTINUOUS_READER_CONFIG {
  ULONG                                 Size;
  size_t                                TransferLength;
  size_t                                HeaderLength;
  size_t                                TrailerLength;
  UCHAR                                 NumPendingReads;
  PWDF_OBJECT_ATTRIBUTES                BufferAttributes;
  PFN_WDF_USB_READER_COMPLETION_ROUTINE EvtUsbTargetPipeReadComplete;
  WDFCONTEXT                            EvtUsbTargetPipeReadCompleteContext;
  PFN_WDF_USB_READERS_FAILED            EvtUsbTargetPipeReadersFailed;
} WDF_USB_CONTINUOUS_READER_CONFIG, *PWDF_USB_CONTINUOUS_READER_CONFIG;

Membres

Size

Taille, en octets, de cette structure.

TransferLength

Longueur maximale, en octets, des données pouvant être reçues de l’appareil.

HeaderLength

Décalage, en octets, dans la mémoire tampon qui reçoit des données de l’appareil. L’infrastructure stocke les données de l’appareil dans une mémoire tampon de lecture, en commençant par la valeur de décalage. En d’autres termes, cet espace précède l’espace de taille TransferLength dans lequel l’infrastructure stocke les données de l’appareil.

TrailerLength

Longueur, en octets, d’un espace de mémoire tampon de fin. Cet espace suit l’espace de taille TransferLength dans lequel l’infrastructure stocke les données de l’appareil.

NumPendingReads

Nombre de demandes de lecture que le framework met en file d’attente pour recevoir des données de la cible d’E/S. Si cette valeur est égale à zéro, l’infrastructure utilise un nombre par défaut de demandes de lecture. Si la valeur spécifiée est supérieure à la valeur maximale autorisée, l’infrastructure utilise la valeur maximale autorisée. Pour plus d’informations sur le membre NumPendingReads , consultez la section Notes suivante.

BufferAttributes

Structure WDF_OBJECT_ATTRIBUTES qui spécifie des attributs d’objet pour l’objet mémoire du framework que le framework crée pour chaque demande de lecture. Ce membre peut être NULL. Vous ne pouvez pas définir le membre ParentObject de la structure WDF_OBJECT_ATTRIBUTES.

EvtUsbTargetPipeReadComplete

Pointeur vers la fonction de rappel EvtUsbTargetPipeReadComplete du pilote.

EvtUsbTargetPipeReadCompleteContext

Pointeur non typé vers les informations de contexte définies par le pilote que le framework transmet à la fonction de rappel EvtUsbTargetPipeReadComplete du pilote.

EvtUsbTargetPipeReadersFailed

Pointeur vers la fonction de rappel EvtUsbTargetPipeReadersFailed du pilote. Ce pointeur est facultatif et peut être NULL. Pour plus d’informations sur ce paramètre, consultez la section Notes de WdfUsbTargetPipeConfigContinuousReader.

Remarques

La structure WDF_USB_CONTINUOUS_READER_CONFIG est utilisée comme entrée de la méthode WdfUsbTargetPipeConfigContinuousReader .

Pour initialiser une structure WDF_USB_CONTINUOUS_READER_CONFIG, le pilote doit appeler WDF_USB_CONTINUOUS_READER_CONFIG_INIT.

Suivez les instructions suivantes lors du choix d’une valeur pour le membre NumPendingReads :

Définissez NumPendingReads sur 0 si vous souhaitez que votre pilote utilise la valeur par défaut de l’infrastructure.
La valeur par défaut est supérieure à 1 et a été déterminée pour fournir des performances raisonnablement bonnes pour de nombreux appareils sur de nombreuses configurations de processeur.
Définissez NumPendingReads sur 1 s’il est important que votre pilote reçoive des mémoires tampons de données dans l’ordre exact dans lequel l’appareil remet les données.
Définissez NumPendingReads sur un nombre qui répond aux exigences de performances de votre appareil, en fonction de mesures de performances approfondies.
Tout d’abord, testez votre appareil avec la valeur par défaut (0) pour NumPendingReads. Vos tests doivent inclure différentes configurations matérielles, notamment différents types et nombres de processeurs, différents contrôleurs hôtes USB et configurations USB. Vous pouvez ensuite expérimenter avec des valeurs plus élevées, en utilisant les mêmes tests. Un pilote qui peut nécessiter une valeur plus élevée est un pilote pour un appareil qui a un taux d’interruption élevé, où les données peuvent être perdues si les interruptions ne sont pas rapidement mises en service.

Une valeur NumPendingReads trop grande peut ralentir les performances d’un système. Vous devez utiliser la valeur la plus faible qui répond à vos exigences de performances. En règle générale, les valeurs supérieures à 3 ou 4 n’améliorent pas le débit des données. Toutefois, des valeurs plus élevées peuvent réduire la latence, ou le risque de données manquantes, sur un canal haute fréquence.