_URB_ISOCH_TRANSFER-Struktur (usb.h)

Artikel
08/07/2023

Die _URB_ISOCH_TRANSFER-Struktur wird von USB-Clienttreibern verwendet, um Daten an eine isochrone Übertragungspipe zu senden oder Daten aus dieser abzurufen.

Syntax

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];
};

Member

Hdr

Ein Zeiger auf eine _URB_HEADER-Struktur , die die URB-Headerinformationen angibt. Hdr.Function muss URB_FUNCTION_ISOCH_TRANSFER sein, und Hdr.Length muss die Größe dieser Datenstruktur mit variabler Länge aufweisen.

PipeHandle

Gibt ein undurchsichtiges Handle für die isochrone Pipe an. Der Hostcontrollertreiber gibt dieses Handle zurück, wenn der Clienttreiber die Gerätekonfiguration mit einer URB vom Typ URB_FUNCTION_SELECT_CONFIGURATION auswählt oder wenn der Clienttreiber die Einstellungen für eine Schnittstelle mit einer URB vom Typ URB_FUNCTION_SELECT_INTERFACE ändert.

TransferFlags

Gibt null, eins oder eine Kombination der folgenden Flags an:

Wert	Bedeutung
USBD_TRANSFER_DIRECTION_IN	Ist so festgelegt, dass Daten von einem Gerät angefordert werden. Um Daten auf ein Gerät zu übertragen, muss dieses Flag eindeutig sein.
USBD_SHORT_TRANSFER_OK	Ist so festgelegt, dass der Hostcontroller anweisen soll, keinen Fehler zurückzugeben, wenn er ein Paket vom Gerät empfängt, das kürzer als die maximale Paketgröße für den Endpunkt ist. Dieses Flag hat keine Auswirkung auf eine isochrone Pipe, da der Bustreiber keinen Fehler zurückgibt, wenn er kurze Pakete auf einer isochronen Pipe empfängt.
USBD_START_ISO_TRANSFER_ASAP	Bewirkt, dass die Übertragung im nächsten Frame beginnt, wenn seit dem Öffnen oder letzten Zurücksetzen der Pipe keine Übertragungen an die Pipe übermittelt wurden. Andernfalls beginnt die Übertragung mit dem ersten Frame, der allen derzeit in der Warteschlange befindlichen Anforderungen für die Pipe folgt. Der tatsächliche Frame, mit dem die Übertragung beginnt, wird vom Hostcontrollertreiber an die Buslatenz angepasst.

TransferBufferLength

Gibt die Länge des in TransferBuffer angegebenen oder in TransferBufferMDL beschriebenen Puffers in Bytes an. Der Hostcontrollertreiber gibt die Anzahl der Bytes zurück, die an die Pipe in diesem Member gesendet oder aus dieser gelesen werden.

TransferBuffer

Ein Zeiger auf einen residenten Puffer für die Übertragung ist NULL , wenn eine MDL in TransferBufferMDL bereitgestellt wird. Der Inhalt dieses Puffers hängt vom Wert von TransferFlags ab. Wenn USBD_TRANSFER_DIRECTION_IN angegeben ist, enthält dieser Puffer Daten, die beim Zurückgeben vom Hostcontrollertreiber vom Gerät gelesen werden. Andernfalls enthält dieser Puffer vom Treiber bereitgestellte Daten für die Übertragung an das Gerät.

TransferBufferMDL

Ein Zeiger auf eine MDL, der einen residenten Puffer beschreibt, ist NULL , wenn ein Puffer in TransferBuffer bereitgestellt wird. Der Inhalt des Puffers hängt vom Wert von TransferFlags ab. Wenn USBD_TRANSFER_DIRECTION_IN angegeben ist, enthält der beschriebene Puffer Daten, die beim Zurückgeben vom Hostcontrollertreiber vom Gerät gelesen werden. Andernfalls enthält der Puffer vom Treiber bereitgestellte Daten für die Übertragung an das Gerät. Diese MDL muss aus einem nicht ausseitigen Pool zugeordnet werden.

UrbLink

Reserviert. Darf nicht verwendet werden.

hca

Reserviert. Darf nicht verwendet werden.

StartFrame

Gibt die Framenummer an, mit der die Übertragung beginnen soll. Diese Variable muss innerhalb eines systemdefinierten Bereichs des aktuellen Frames liegen. Der Bereich wird durch die konstante USBD_ISO_START_FRAME_RANGE angegeben.

Wenn START_ISO_TRANSFER_ASAP in TransferFlags festgelegt ist, enthält dieses Element die Framenummer, mit der die Übertragung begonnen hat, wenn die Anforderung vom Hostcontrollertreiber zurückgegeben wird. Andernfalls muss dieser Member die Framenummer enthalten, mit der diese Übertragung beginnt.

NumberOfPackets

Gibt die Anzahl der Pakete an, die vom Arrayelement IsoPacket mit variabler Länge beschrieben werden.

ErrorCount

Enthält die Anzahl der Pakete, die beim Zurückgeben vom Hostcontrollertreiber mit einer Fehlerbedingung abgeschlossen wurden.

IsoPacket[1]

Enthält ein Array mit variabler Länge von USBD_ISO_PACKET_DESCRIPTOR Strukturen, die die isochronen Übertragungspakete beschreiben, die auf dem USB-Bus übertragen werden sollen. Weitere Informationen zu diesem Member finden Sie im Abschnitt Hinweise.

Hinweise

Der USB-Bustreiber gibt immer den Wert USBD_STATUS_SUCCESS in Hdr.Status zurück, es sei denn, jedes Paket in der Übertragung hat einen Fehler generiert oder die Anforderung war nicht wohlgeformt und konnte überhaupt nicht ausgeführt werden. Die folgende Tabelle enthält mögliche Fehlercodes, die in Hdr.Status zurückgegeben werden.

Fehlerwert	Bedeutung
USBD_STATUS_ISOCH_REQUEST_FAILED	Gibt an, dass jedes Paket einer isochronen Anforderung mit Fehlern abgeschlossen wurde.
USBD_STATUS_BAD_START_FRAME	Gibt an, dass sich der angeforderte Startframe nicht innerhalb USBD_ISO_START_FRAME_RANGE des aktuellen USB-Frames befindet.
USBD_ISO_NOT_ACCESSED_LATE	Gibt an, dass jedes Paket basierend auf dem angeforderten Startframe zu spät für das Senden des Pakets übermittelt wurde.
USBD_STATUS_INVALID_PARAMETER	Gibt an, dass einer der URB-Parameter falsch war.

Bevor der Hostcontroller eine isochrone Anforderung an ein USB-Gerät sendet, benötigt er Informationen über den Endpunkt des Geräts, an den er Daten senden oder empfangen muss. Diese Informationen werden in Endpunktdeskriptoren (USB_ENDPOINT_DESCRIPTOR) gespeichert, die vom ausgewählten Konfigurationsdeskriptor abgerufen werden. Nachdem der Bustreiber den Endpunktdeskriptor abgerufen hat, erstellt er eine isochrone Übertragungspipe, um die Datenübertragung einzurichten. Die Attribute der Pipe werden in der USBD_PIPE_INFORMATION-Struktur gespeichert. Für isochrone Übertragungen werden die Member wie folgt festgelegt:

Das PipeType-Element gibt den Übertragungstyp an und ist auf UsbdPipeTypeIsochronous festgelegt.
Das MaximumPacketSize-Element gibt die Datenmenge in Bytes an, die ein Paket ausmacht. Bei isochronen Übertragungen ist die Paketgröße fest und kann einen Wert zwischen 0 und 1024 aufweisen. Die Paketgröße ist entweder gleich oder kleiner als der wMaxPacketSize-Wert des Endpunktdeskriptors.
Das Interval-Element wird vom bInterval-Wert des Endpunktdeskriptors abgeleitet. Dieser Wert wird verwendet, um den Abrufzeitraum zu berechnen, der die Häufigkeit angibt, mit der Daten auf dem Bus gesendet werden. Bei Geräten mit voller Geschwindigkeit wird der Zeitraum in Einheiten von 1 Millisekundenrahmen gemessen; bei Hochgeschwindigkeitsgeräten wird der Zeitraum in Microframes gemessen.

Der Hostcontroller bestimmt auch die Datenmenge, die (innerhalb eines Frames oder eines Microframes) übertragen werden kann, je nach Gerätetyp. Diese Informationen sind in Bits 12.. 11 von wMaxPacketSize im Endpunktdeskriptor verfügbar.

Bei Geräten mit voller Geschwindigkeit kann nur ein Paket innerhalb eines Frames übertragen werden; Bits 12.. 11 sind reserviert und auf Null festgelegt.

Bei Hochgeschwindigkeitsgeräten können Daten in einem einzelnen Paket übertragen werden oder mehrere Pakete innerhalb eines Microframes umfassen. Wenn Bits 12.. 11 auf n festgelegt sind, können Sie Bytes pro Microframe übertragen (n+1)*MaximumPacketSize . Bits 12.. 11 , die auf 0 festgelegt sind, geben an, dass nur ein Paket in einem Microframe übertragen werden kann. Wenn Bits 12.. 11 auf 1 festgelegt sind, kann der Hostcontroller zwei Pakete in einem Microframe übertragen.

Das IsoPacket-Element von _URB_ISOCH_TRANSFER ist ein Array von USBD_ISO_PACKET_DESCRIPTOR , das das Layout des Übertragungspuffers beschreibt. Jedes Element im Array korreliert mit Daten, die in einem Mikroframe übertragen werden. Wenn IsoPacketüber n-Elemente verfügt, verwenden die Hostcontrollerübertragungen n Frames (für Geräte mit voller Geschwindigkeit) oder Microframes (für Hochgeschwindigkeitsgeräte) für die Datenübertragung. Das IsoPacket[i]. Offsetmember wird verwendet, um die Datenmenge zu verfolgen, die gesendet oder empfangen werden soll. Dies erfolgt durch Festlegen eines Byteoffsets vom Anfang des gesamten Übertragungspuffers für die Anforderung.

Beispielsweise stehen fünf Microframes zur Übertragung von Paketen mit 1024 Bytegröße zur Verfügung.

Wenn Bits 12.. 11 auf 0 festgelegt sind (was ein einzelnes Paket pro Microframeübertragung angibt), enthält IsoPacket die folgenden Einträge:

Microframe 1 IsoPacket.Element[0].Offset = 0 (Startadresse)

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

Wenn Bits 12.. 11 auf 1 festgelegt sind (was zwei Pakete pro Microframe angibt), enthält IsoPacket die folgenden Einträge:

Microframe 1 IsoPacket.Element[0].Offset = 0 (Startadresse)

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

Hinweis Bei mehreren Paketen gibt der Offsetwert die Größen für alle Pakete innerhalb des Microframes an.

Das IsoPacket[i]. Längenelement wird vom Hostcontroller aktualisiert, um die tatsächliche Anzahl von Bytes anzugeben, die vom Gerät für isochrone IN-Übertragungen empfangen werden. IsoPacket[i]. Die Länge wird nicht für isochrone OUT-Übertragungen verwendet.

Treiber können das Makro GET_ISO_URB_SIZE verwenden, um die Größe zu bestimmen, die für die gesamte URB erforderlich ist. Wenn die Länge zu klein ist, um den für dieses Paket reservierten Speicherplatz zu füllen, hinterlässt der Bustreiber eine Lücke vom Ende der abgerufenen Daten bis zum Offset für das nächste Paket. Der Bustreiber passt die Offsets nicht an, um zu vermeiden, dass puffern.

Die TransferBuffer - oder TransferBufferMDL-Member müssen einen nahezu zusammenhängenden Puffer angeben.

Behandeln Sie andere Member, die Teil dieser Struktur sind, aber hier nicht beschrieben werden, als undurchsichtig. Sie sind für die Systemnutzung reserviert.