Fonctions WinUSB pour la modification de la stratégie de canal

  • Article

Pour permettre aux applications d’obtenir et de définir les paramètres de stratégie par défaut d’un canal de point de terminaison, Winusb.dll expose la fonction WinUsb_GetPipePolicy pour récupérer la stratégie par défaut du canal. La fonction WinUsb_SetPipePolicy permet à une application de définir le paramètre de stratégie sur une nouvelle valeur.

WinUSB vous permet de modifier son comportement par défaut en appliquant des stratégies au canal d’un point de terminaison. En utilisant ces stratégies, vous pouvez configurer WinUSB pour qu’il corresponde au mieux à votre appareil à ses fonctionnalités. Le tableau suivant fournit la liste des stratégies de canal prises en charge par WinUSB.

Notes

Les stratégies décrites dans le tableau sont valides uniquement pour les points de terminaison spécifiés. La définition de la stratégie sur d’autres points de terminaison n’a aucun effet sur le comportement de WinUSB pour les demandes de lecture ou d’écriture.

Numéro de stratégie Nom de stratégie Description Point de terminaison (direction) Valeur par défaut
0x01 SHORT_PACKET_TERMINATE Envoie un paquet de longueur nulle pour une demande d’écriture dans laquelle la mémoire tampon est un multiple de la taille de paquet maximale prise en charge par le point de terminaison. Bulk (OUT)

Interruption (OUT)		 FALSE
0x02 AUTO_CLEAR_STALL Efface automatiquement un canal bloqué sans arrêter le flux de données. Bulk (IN)

Interruption (IN)		 FALSE
0x03 PIPE_TRANSFER_TIMEOUT Attend un intervalle de délai d’attente, en millisecondes, avant d’annuler la demande. Bulk (IN)

Bulk (OUT)

Interruption (IN)

Interruption (OUT)		 5 secondes (5 000 millisecondes) pour le contrôle ; 0 pour les autres
0x04 IGNORE_SHORT_PACKETS Termine une demande de lecture lorsqu’un paquet court est reçu ou qu’un certain nombre d’octets est lu. Si la taille du fichier est inconnue, la demande se termine à un paquet court. Bulk (IN)

Interruption (IN)		 FALSE
0x05 ALLOW_PARTIAL_READS Autorise les demandes de lecture à partir d’un appareil qui retourne plus de données que demandé par l’appelant. Bulk (IN)

Interruption (IN)		 TRUE
0x06 AUTO_FLUSH Enregistre les données excédentaires de la demande de lecture et les ajoute à la demande de lecture suivante ou ignore les données excédentaires. Bulk (IN)

Interruption (IN)		 FALSE
0x07 RAW_IO Contourne la mise en file d’attente et la gestion des erreurs pour améliorer les performances de plusieurs demandes de lecture. Bulk (IN)

Interruption (IN)		 FALSE
0x08 MAXIMUM_TRANSFER_SIZE Obtient la taille maximale d’un transfert USB pris en charge par WinUSB. Il s’agit d’une stratégie en lecture seule qui peut être récupérée en appelant WinUsb_GetPipePolicy. Bulk (IN)

Bulk (OUT)

Interruption (IN)

Interruption (OUT)
0x09 RESET_PIPE_ON_RESUME Réinitialise le canal du point de terminaison après la reprise de la suspension avant d’accepter de nouvelles demandes. Bulk (IN)

Bulk (OUT)

Interruption (IN)

Interruption (OUT)		 FALSE

Le tableau suivant identifie les meilleures pratiques d’utilisation de chacune des stratégies de canal et décrit le comportement résultant lorsque la stratégie est activée.

Stratégie Activer si... Comportement
SHORT_PACKET_TERMINATE(0x01) L’appareil nécessite que les transferts OUT se terminent par un paquet de longueur nulle. La plupart des appareils n’ont pas cette exigence. Si cette option est activée (la valeur du paramètre de stratégie est TRUE ou différente de zéro), chaque demande d’écriture qui est un multiple de la taille de paquet maximale prise en charge par le point de terminaison est suivie d’un paquet de longueur nulle.

Après avoir envoyé des données au contrôleur hôte, WinUSB envoie une demande d’écriture avec un paquet de longueur nulle, puis termine la requête qui a été créée par WinUsb_WritePipe.
AUTO_CLEAR_STALL Vous ne souhaitez pas que les transferts ayant échoué laissent le point de terminaison dans un état bloqué. Cette stratégie est utile uniquement lorsque vous avez plusieurs demandes de lecture en attente au point de terminaison lorsque RAW_IO est désactivé.
  • Si cette option est activée (la valeur du paramètre de stratégie est TRUE ou différente de zéro), une condition de blocage est automatiquement effacée. Ce paramètre de stratégie n’affecte pas les canaux de contrôle.

    Lorsqu’une demande de lecture échoue et que le contrôleur hôte retourne un status autre que STATUS_CANCELLED ou STATUS_DEVICE_NOT_CONNECTED, WinUSB réinitialise le canal avant de terminer la demande ayant échoué. La réinitialisation du canal efface la condition de blocage sans interrompre le flux de données. Les données continuent de circuler dans les points de terminaison tant que de nouveaux transferts continuent d’arriver à partir de l’appareil. Un nouveau transfert peut inclure un transfert qui se trouvait dans la file d’attente lorsque le blocage s’est produit.

    L’activation de cette stratégie n’a pas d’impact significatif sur les performances.

  • S’il est désactivé (la valeur du paramètre de stratégie est FALSE ou zéro), tous les transferts qui arrivent au point de terminaison après le transfert bloqué échouent jusqu’à ce que l’appelant réinitialise manuellement le canal du point de terminaison en appelant WinUsb_ResetPipe.
PIPE_TRANSFER_TIMEOUT Vous vous attendez à ce que les transferts vers un point de terminaison se terminent dans un délai spécifique.
  • S’il est défini sur zéro (valeur par défaut), les transferts n’expirent pas, car le contrôleur hôte n’annule pas le transfert. Dans ce cas, le transfert attend indéfiniment jusqu’à ce qu’il soit annulé manuellement ou que le transfert se termine normalement.
  • S’il est défini sur une valeur différente de zéro (intervalle de délai d’attente), le contrôleur hôte démarre un minuteur lorsqu’il reçoit la demande de transfert. Lorsque le minuteur dépasse l’intervalle de délai d’attente défini, la requête est annulée.

    Une pénalité de performances mineure se produit en raison de la gestion du minuteur.

    Les demandes n’expirent pas pendant l’attente dans une file d’attente WinUSB.

    Dans Windows Vista, pour tous les transferts (à l’exception des transferts avec RAW_IO activé), WinUSB met en file d’attente la requête jusqu’à ce que tous les transferts précédents sur le point de terminaison de destination soient terminés. Le contrôleur hôte n’inclut pas la durée de mise en file d’attente dans le calcul de l’intervalle de délai d’attente.

    Une fois RAW_IO activé, WinUSB ne met pas la demande en file d’attente. Au lieu de cela, il transmet la requête directement à la pile USB, que la pile USB soit occupée à traiter les transferts précédents. Si la pile USB est occupée, elle peut retarder le traitement de la nouvelle requête. Cela peut entraîner un délai d’attente.
IGNORE_SHORT_PACKETS RAW_IO est désactivé et vous ne souhaitez pas que les paquets courts terminent les demandes de lecture.
  • Si cette option est activée (la valeur du paramètre de stratégie est TRUE ou différente de zéro), le contrôleur hôte n’effectue pas une opération de lecture immédiatement après avoir reçu un paquet court. Au lieu de cela, il termine l’opération uniquement si :
    • Une erreur se produit.
    • La demande est annulée.
    • Tous les octets demandés ont été reçus.
  • S’il est désactivé (la valeur du paramètre de stratégie est FALSE ou zéro), le contrôleur hôte effectue une opération de lecture après avoir lu le nombre d’octets demandé ou reçu un paquet court.
ALLOW_PARTIAL_READS L’appareil peut envoyer plus de données que demandé si la taille de votre mémoire tampon de requête est un multiple de la taille maximale des paquets de point de terminaison.

Utilisez si votre application souhaite lire quelques octets pour déterminer le nombre total d’octets à lire.
  • S’il est désactivé (la valeur du paramètre de stratégie est FALSE ou zéro) et que l’appareil retourne plus de données que ce qui a été demandé, WinUSB termine la requête avec une erreur.
  • Si cette option est activée (la valeur du paramètre de stratégie est TRUE ou différente de zéro) et que l’appareil retourne plus de données que ce qui a été demandé, WinUSB peut (en fonction des paramètres de AUTO_FLUSH) ajouter les données excédentaires de la demande de lecture au début de la demande de lecture suivante ou ignorer les données excédentaires.

    Si cette option est activée, WinUSB termine immédiatement les demandes de lecture pour zéro octet et n’envoie pas les demandes dans la pile.
AUTO_FLUSH ALLOW_PARTIAL_READS stratégie est activée.

L’appareil peut envoyer plus de données que demandé, et votre application ne nécessite aucune autre donnée. Cela est possible si la taille de votre mémoire tampon de requête est un multiple de la taille maximale du paquet de point de terminaison.		 AUTO_FLUSH définit le comportement de WinUSB lorsque ALLOW_PARTIAL_READS est activé. Si ALLOW_PARTIAL_READS est désactivé, la valeur AUTO_FLUSH est ignorée par WinUSB.

WinUSB peut ignorer les données restantes ou les envoyer avec la demande de lecture suivante de l’appelant.

  • Si cette option est activée (la valeur du paramètre de stratégie est TRUE ou différente de zéro), WinUSB ignore les octets supplémentaires sans code d’erreur.
  • S’il est désactivé (la valeur du paramètre de stratégie est FALSE ou zéro), WinUSB enregistre les octets supplémentaires, les ajoute au début de la demande de lecture suivante de l’appelant, puis envoie les données à l’appelant lors de l’opération de lecture suivante.
RAW_IO Les performances sont une priorité et l’application envoie des demandes de lecture simultanées au même point de terminaison.

RAW_IO impose certaines restrictions sur la mémoire tampon passée par l’appelant dans WinUsb_ReadPipe :

  • La longueur de la mémoire tampon doit être un multiple de la taille maximale du paquet de point de terminaison.
  • La longueur doit être inférieure ou égale à la valeur de MAXIMUM_TRANSFER_SIZE récupérées par WinUsb_GetPipePolicy.
 Si cette option est activée, les transferts contournent la mise en file d’attente et la gestion des erreurs pour améliorer les performances de plusieurs demandes de lecture. WinUSB gère les demandes de lecture comme suit :

  • Une requête qui n’est pas un multiple de la taille maximale du paquet de point de terminaison échoue.
  • Une requête supérieure à la taille de transfert maximale prise en charge par WinUSB échoue.
  • Toutes les requêtes bien formées sont immédiatement envoyées à la pile de cœurs USB pour être planifiées dans le contrôleur hôte.


L’activation de ce paramètre améliore considérablement les performances de plusieurs demandes de lecture en réduisant le délai entre le dernier paquet d’un transfert et le premier paquet du transfert suivant.
RESET_PIPE_ON_RESUME L’appareil ne conserve pas son état bascule de données sur la suspension. Lors de la reprise de la suspension, WinUSB réinitialise le point de terminaison avant de permettre à l’appelant d’envoyer de nouvelles demandes au point de terminaison.