structure _URB_ISOCH_TRANSFER (usb.h)

Article
02/07/2025

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 isochronique.

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 _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 la taille de cette structure de données de longueur variable.

PipeHandle

Spécifie un handle opaque au canal isochrone. Le pilote du contrôleur hôte retourne ce handle lorsque le pilote client sélectionne la configuration de l’appareil avec un URB de type URB_FUNCTION_SELECT_CONFIGURATION ou lorsque le pilote client modifie les paramètres d’une interface avec un 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 diriger le contrôleur hôte de ne pas retourner une erreur lorsqu’il reçoit un paquet de l’appareil plus court que la taille maximale du paquet pour le point de terminaison. Cet indicateur n’a aucun effet sur un canal isochroneux, car le pilote de bus ne retourne pas d’erreur lorsqu’il reçoit des paquets courts sur un canal isochrone.
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 ou la dernière réinitialisation du canal. Sinon, le transfert commence sur la première image qui suit toutes les demandes actuellement mises en file d’attente pour le canal. Le frame réel sur lequel le transfert commence sera ajusté 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 un MDL est fourni 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 à partir du pilote du contrôleur hôte. Sinon, cette mémoire tampon contient des données fournies par le pilote pour le transfert vers l’appareil.

TransferBufferMDL

Un pointeur vers un 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 lors du retour du pilote du contrôleur hôte. Sinon, la mémoire tampon contient des données fournies par le pilote pour le transfert vers l’appareil. Ce MDL doit être alloué à partir d’un pool non paginé.

UrbLink

Réservé. N’utilisez pas.

hca

Réservé. N’utilisez pas.

StartFrame

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

Si START_ISO_TRANSFER_ASAP est défini dans TransferFlags, ce membre contient le numéro d’image sur lequel le transfert a commencé, lorsque la requête est retournée par le pilote du contrôleur hôte. Dans le cas contraire, ce membre doit contenir le numéro d’image 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 lors du retour 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 isochrones à 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 requête 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 isochrone a été terminé avec des erreurs.
USBD_STATUS_BAD_START_FRAME	Indique que l’image de démarrage demandée n’est pas dans USBD_ISO_START_FRAME_RANGE du cadre USB actuel.
USBD_ISO_NOT_ACCESSED_LATE	Indique que chaque paquet a été envoyé trop tard pour que le paquet soit envoyé, en fonction de l’image de démarrage demandée.
USBD_STATUS_INVALID_PARAMETER	Indique qu’un des paramètres URB était incorrect.

Avant que le contrôleur hôte envoie une demande isochroneuse à un appareil 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) 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 isochrone 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 isochrones, 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 à vitesse totale, la période est mesurée en unités de 1 millisecondes ; 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 qui peuvent être transférées (au sein d’une trame ou d’un microframe) en fonction du type d’appareil. Ces informations sont disponibles en bits 12.. 11 de wMaxPacketSize dans le descripteur de point de terminaison.

Pour les appareils à vitesse totale, un seul paquet peut être transféré dans une trame ; bits 12.. 11 sont réservées et définies sur zéro.

Pour les appareils à grande vitesse, les données peuvent être transférées dans un paquet unique ou peuvent s’étendre sur plusieurs paquets, au sein d’un microframe. Si les bits 12.. 11 sont définies sur n, vous pouvez transférer (n+1)*MaximumPacketSize octets par microframe. Bits 12.. 11 défini sur zéro indiquent qu’un seul paquet peut être transféré dans un microframe. Si les bits 12.. 11 sont définies 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, le contrôleur hôte transfère l’utilisation n frames (pour les appareils à vitesse totale) ou les microframes (pour les appareils à grande vitesse) pour transférer des données. Le IsoPacket[i]. Le décalage membre est utilisé pour suivre la quantité de données à envoyer ou à recevoir. Pour ce faire, définissez un décalage d’octet à partir du début de la mémoire tampon de transfert entière pour la requête.

Par exemple, il existe cinq microframes disponibles pour transférer des paquets de taille d’octet 1024.

Si les bits 12.. 11 sont définies 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éfinies 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

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

Le IsoPacket[i]. La longueur membre est mise à jour par le contrôleur hôte pour indiquer le nombre réel d’octets reçus de l’appareil pour les transferts IN isochronous. IsoPacket[i]. 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 écart 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 perdre de 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.