structure _URB_ISOCH_TRANSFER (usb.h)

Article
08/07/2023

La structure _URB_ISOCH_TRANSFER est utilisée par les pilotes clients USB pour envoyer ou récupérer des données à partir d’un canal de transfert isochroneuse.

Syntaxe

struct _URB_ISOCH_TRANSFER {
  struct _URB_HEADER         Hdr;
  USBD_PIPE_HANDLE           PipeHandle;
  ULONG                      TransferFlags;
  ULONG                      TransferBufferLength;
  PVOID                      TransferBuffer;
  PMDL                       TransferBufferMDL;
  struct _URB                *UrbLink;
  struct _URB_HCD_AREA       hca;
  ULONG                      StartFrame;
  ULONG                      NumberOfPackets;
  ULONG                      ErrorCount;
  USBD_ISO_PACKET_DESCRIPTOR IsoPacket[1];
};

Membres

Hdr

Pointeur vers une structure de _URB_HEADER qui spécifie les informations d’en-tête URB. Hdr.Function doit être URB_FUNCTION_ISOCH_TRANSFER, et Hdr.Length doit être de la taille de cette structure de données de longueur variable.

PipeHandle

Spécifie une poignée opaque pour le canal isochroque. Le pilote du contrôleur hôte retourne ce handle quand le pilote client sélectionne la configuration du périphérique avec un URB de type URB_FUNCTION_SELECT_CONFIGURATION ou quand le pilote client modifie les paramètres d’une interface avec une interface URB de type URB_FUNCTION_SELECT_INTERFACE.

TransferFlags

Spécifie zéro, un ou une combinaison des indicateurs suivants :

Valeur	Signification
USBD_TRANSFER_DIRECTION_IN	Est défini pour demander des données à partir d’un appareil. Pour transférer des données vers un appareil, cet indicateur doit être clair.
USBD_SHORT_TRANSFER_OK	Est défini pour indiquer au contrôleur hôte de ne pas retourner d’erreur lorsqu’il reçoit un paquet de l’appareil qui est plus court que la taille de paquet maximale pour le point de terminaison. Cet indicateur n’a aucun effet sur un canal isochroque, car le pilote de bus ne retourne pas d’erreur lorsqu’il reçoit des paquets courts sur un canal isochroque.
USBD_START_ISO_TRANSFER_ASAP	Provoque le début du transfert sur l’image suivante, si aucun transfert n’a été soumis au canal depuis l’ouverture du canal ou la dernière réinitialisation. Sinon, le transfert commence sur la première image qui suit toutes les demandes actuellement mises en file d’attente pour le canal. L’image réelle sur laquelle le transfert commence sera ajustée pour la latence du bus par le pilote du contrôleur hôte.

TransferBufferLength

Spécifie la longueur, en octets, de la mémoire tampon spécifiée dans TransferBuffer ou décrite dans TransferBufferMDL. Le pilote du contrôleur hôte retourne le nombre d’octets envoyés ou lus à partir du canal dans ce membre.

TransferBuffer

Un pointeur vers une mémoire tampon résidente pour le transfert est NULL si une MDL est fournie dans TransferBufferMDL. Le contenu de cette mémoire tampon dépend de la valeur de TransferFlags. Si USBD_TRANSFER_DIRECTION_IN est spécifié, cette mémoire tampon contient des données lues à partir de l’appareil au retour du pilote du contrôleur hôte. Sinon, cette mémoire tampon contient des données fournies par le pilote à transférer vers l’appareil.

TransferBufferMDL

Un pointeur vers une MDL qui décrit une mémoire tampon résidente est NULL si une mémoire tampon est fournie dans TransferBuffer. Le contenu de la mémoire tampon dépend de la valeur de TransferFlags. Si USBD_TRANSFER_DIRECTION_IN est spécifié, la mémoire tampon décrite contient des données lues à partir de l’appareil au retour du pilote du contrôleur hôte. Sinon, la mémoire tampon contient des données fournies par le pilote à transférer vers l’appareil. Cette MDL doit être allouée à partir d’un pool non paginé.

UrbLink

Réservé. Ne pas utiliser.

hca

Réservé. Ne pas utiliser.

StartFrame

Spécifie le numéro de trame sur lequel le transfert doit commencer. Cette variable doit se trouver dans une plage définie par le système de l’image actuelle. La plage est spécifiée par la constante USBD_ISO_START_FRAME_RANGE.

Si START_ISO_TRANSFER_ASAP est défini dans TransferFlags, ce membre contient le numéro de trame sur lequel le transfert a commencé, lorsque la demande est retournée par le pilote du contrôleur hôte. Sinon, ce membre doit contenir le numéro de trame sur lequel ce transfert commence.

NumberOfPackets

Spécifie le nombre de paquets décrits par le membre de tableau de longueur variable IsoPacket.

ErrorCount

Contient le nombre de paquets qui se sont terminés avec une condition d’erreur au retour à partir du pilote du contrôleur hôte.

IsoPacket[1]

Contient un tableau de longueur variable de structures USBD_ISO_PACKET_DESCRIPTOR qui décrivent les paquets de transfert isochroneuses à transférer sur le bus USB. Pour plus d’informations sur ce membre, consultez la section Remarques.

Remarques

Le pilote de bus USB retourne toujours une valeur de USBD_STATUS_SUCCESS dans Hdr.Status, sauf si chaque paquet du transfert a généré une erreur ou si la demande n’a pas été correctement formée et n’a pas pu être exécutée du tout. Le tableau suivant inclut les codes d’erreur possibles retournés dans Hdr.Status.

Valeur d’erreur	Signification
USBD_STATUS_ISOCH_REQUEST_FAILED	Indique que chaque paquet d’une requête isochroneuse a été terminé avec des erreurs.
USBD_STATUS_BAD_START_FRAME	Indique que le frame de début demandé n’est pas dans USBD_ISO_START_FRAME_RANGE du frame USB actuel.
USBD_ISO_NOT_ACCESSED_LATE	Indique que chaque paquet a été envoyé trop tard pour que le paquet soit envoyé, en fonction du frame de début demandé.
USBD_STATUS_INVALID_PARAMETER	Indique que l’un des paramètres URB était incorrect.

Avant que le contrôleur hôte envoie une requête isochroneuse à un périphérique USB, il nécessite des informations sur le point de terminaison de l’appareil auquel il doit envoyer ou recevoir des données. Ces informations sont stockées dans des descripteurs de point de terminaison (USB_ENDPOINT_DESCRIPTOR) qui sont récupérés à partir du descripteur de configuration sélectionné. Une fois que le pilote de bus obtient le descripteur de point de terminaison, il crée un canal de transfert isochroque pour configurer le transfert de données. Les attributs du canal sont stockés dans la structure USBD_PIPE_INFORMATION . Pour les transferts isochrones, les membres sont définis comme suit :

Le membre PipeType spécifie le type de transfert et est défini sur UsbdPipeTypeIsochronous.
Le membre MaximumPacketSize spécifie la quantité de données, en octets, qui constitue un paquet. Pour les transferts isochrone, la taille du paquet est fixe et peut être une valeur comprise entre 0 et 1024. La taille du paquet est égale ou inférieure à la valeur wMaxPacketSize du descripteur de point de terminaison.
Le membre Interval est dérivé de la valeur bInterval du descripteur de point de terminaison. Cette valeur est utilisée pour calculer la période d’interrogation qui indique la fréquence à laquelle les données sont envoyées sur le bus. Pour les appareils à pleine vitesse, la période est mesurée en unités d’images de 1 milliseconde ; pour les appareils à grande vitesse, la période est mesurée en microframes.

Le contrôleur hôte détermine également la quantité de données pouvant être transférées (dans un cadre ou un microframe) en fonction du type d’appareil. Ces informations sont disponibles dans les bits 12.. 11 de wMaxPacketSize dans le descripteur de point de terminaison.

Pour les appareils à pleine vitesse, un seul paquet peut être transféré dans un cadre ; les bits 12.. 11 sont réservés et définis sur zéro.

Pour les appareils à haut débit, les données peuvent être transférées en un seul paquet ou peuvent s’étendre sur plusieurs paquets, au sein d’un microframe. Si les bits 12.. 11 sont définis sur n, vous pouvez transférer (n+1)*MaximumPacketSize des octets par microframe. Les bits 12.. 11 définis sur zéro indiquent qu’un seul paquet peut être transféré dans un microframe. Si les bits 12.. 11 sont définis sur 1, le contrôleur hôte peut transférer deux paquets dans un microframe.

Le membre IsoPacket de _URB_ISOCH_TRANSFER est un tableau de USBD_ISO_PACKET_DESCRIPTOR qui décrit la disposition de la mémoire tampon de transfert. Chaque élément du tableau est corrélé aux données transférées dans un microframe. Si IsoPacket a n éléments, les transferts du contrôleur hôte utilisent n frames (pour les appareils à pleine vitesse) ou des microframes (pour les appareils haute vitesse) pour transférer des données. IsoPacket[i]. Le membre offset est utilisé pour suivre la quantité de données à envoyer ou à recevoir. Pour ce faire, définissez un décalage d’octets à partir du début de la mémoire tampon de transfert entière pour la requête.

Par exemple, cinq microframes sont disponibles pour transférer des paquets de 1 024 octets.

Si les bits 12.. 11 sont définis sur zéro (indiquant un paquet unique par transfert de microframe), IsoPacket contient les entrées suivantes :

Microframe 1 IsoPacket.Element[0].Offset = 0 (adresse de début)

Microframe 2 IsoPacket.Element[1].Offset = 1024

Microframe 3 IsoPacket.Element[2].Offset = 2048

Microframe 4 IsoPacket.Element[3].Offset = 3072

Microframe 5 IsoPacket.Element[4].Offset = 4096

Si les bits 12.. 11 sont définis sur 1 (indiquant deux paquets par microframe), IsoPacket contient les entrées suivantes :

Microframe 1 IsoPacket.Element[0].Offset = 0 (adresse de début)

Microframe 2 IsoPacket.Element[1].Offset = 2048

Microframe 3 IsoPacket.Element[2].Offset = 4096

Microframe 4 IsoPacket.Element[3].Offset = 6144

Microframe 5 IsoPacket.Element[4].Offset = 8192

Note Pour plusieurs paquets, la valeur de décalage indique la taille de tous les paquets au sein du microframe.

IsoPacket[i]. Le membre de longueur est mis à jour par le contrôleur hôte pour indiquer le nombre réel d’octets reçus de l’appareil pour les transferts IN isochrones. IsoPacket[i]. La longueur n’est pas utilisée pour les transferts OUT isochronous.

Les pilotes peuvent utiliser la macro GET_ISO_URB_SIZE pour déterminer la taille nécessaire pour contenir l’intégralité de l’URB. Si la longueur est trop petite pour remplir l’espace réservé à ce paquet, le pilote de bus laisse un espace entre la fin des données récupérées et le décalage du paquet suivant. Le pilote de bus n’ajuste pas les décalages pour éviter de gaspiller l’espace tampon.

Les membres TransferBuffer ou TransferBufferMDL doivent spécifier une mémoire tampon pratiquement contiguë.

Traitez les autres membres qui font partie de cette structure, mais qui ne sont pas décrits ici comme opaques. Ils sont réservés à l’utilisation du système.