Partager via

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 le mieux à votre appareil à ses fonctionnalités. Le tableau suivant fournit la liste des stratégies de canal prises en charge par WinUSB.

Remarque

Les stratégies décrites dans la table 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 la 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 maximale du paquet pris en charge par le point de terminaison. En bloc (OUT)

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

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

En bloc (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 sont lus. Si la taille du fichier est inconnue, la demande est arrêtée à un paquet court. En bloc (IN)

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

Interruption (IN)		 VRAI
0x06 AUTO_FLUSH Enregistre les données excédentaires de la demande de lecture et l’ajoute à la demande de lecture suivante ou ignore les données excédentaires. En bloc (IN)

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

Interruption (IN)		 FAUX
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. En bloc (IN)

En bloc (OUT)

Interruption (IN)

Interruption (OUT)
0x09 RESET_PIPE_ON_RESUME Réinitialise le canal du point de terminaison après avoir repris sa suspension avant d’accepter de nouvelles demandes. En bloc (IN)

En bloc (OUT)

Interruption (IN)

Interruption (OUT)		 FAUX

Le tableau suivant identifie les meilleures pratiques pour utiliser 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 soient arrêtés avec un paquet de longueur nulle. La plupart des appareils n’ont pas cette exigence. Si cette valeur 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 maximale du paquet pris 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 créée par WinUsb_WritePipe.
AUTO_CLEAR_STALL Vous ne souhaitez pas que les transferts ayant échoué quittent le point de terminaison dans un état bloqué. Cette stratégie est utile uniquement lorsque vous avez plusieurs demandes de lecture en attente sur le point de terminaison lorsque RAW_IO est désactivée.
  • 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 effacée automatiquement. 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 état autre que STATUS_CANCELLED ou STATUS_DEVICE_NOT_CONNECTED, WinUSB réinitialise le canal avant d’effectuer 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 les nouveaux transferts continuent d’arriver de l’appareil. Un nouveau transfert peut inclure celui qui était 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 l’échec du transfert bloqué jusqu’à ce que l’appelant réinitialise manuellement le canal du point de terminaison en appelant WinUsb_ResetPipe.
PIPE_TRANSFER_TIMEOUT Vous prévoyez que les transferts vers un point de terminaison se terminent dans un délai spécifique.
  • Si la valeur est 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é mineure sur les performances se produit en raison de la gestion du minuteur.

    Les demandes ne expirent pas en attendant dans une file d’attente WinUSB.

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

    Avec RAW_IO activé, WinUSB ne met pas en file d’attente la requête. Au lieu de cela, il transmet la requête directement à la pile USB, si la pile USB est 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 valeur est activée (la valeur du paramètre de stratégie est TRUE ou différente de zéro), le contrôleur hôte ne termine pas une opération de lecture immédiatement après avoir reçu un paquet court. Au lieu de cela, elle 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 une fois qu’il a lu le nombre demandé d’octets ou a 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.
  • Si cette valeur est désactivée (la valeur du paramètre de stratégie est FALSE ou zéro) et que l’appareil retourne plus de données que demandé, WinUSB termine la requête avec une erreur.
  • Si cette valeur 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 demandé, WinUSB peut (selon les paramètres 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 octets 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 des paquets de point de terminaison.		 AUTO_FLUSH définit le comportement de WinUSB quand 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 l’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.
  • Si 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 à 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ée 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 des paquets de point de terminaison échoue.
  • Une requête supérieure à la taille maximale de transfert prise en charge par WinUSB échoue.
  • Toutes les requêtes bien formées sont immédiatement envoyées à la pile de cœurs USB à planifier 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 entre les interruptions. 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.