Freigeben über

WinUSB-Funktionen für die Änderung von Piperichtlinien

  • Artikel

Damit Anwendungen die Standardrichtlinienparameter einer Endpunktpipe abrufen und festlegen können, macht Winusb.dll die WinUsb_GetPipePolicy-Funktion verfügbar, um die Standardrichtlinie der Pipe abzurufen. Die WinUsb_SetPipePolicy-Funktion ermöglicht es einer Anwendung, den Richtlinienparameter auf einen neuen Wert festzulegen.

Mit WinUSB können Sie das Standardverhalten ändern, indem Sie Richtlinien auf die Pipe eines Endpunkts anwenden. Mithilfe dieser Richtlinien können Sie WinUSB so konfigurieren, dass Ihr Gerät seinen Funktionen am besten entspricht. Die folgende Tabelle enthält eine Liste der von WinUSB unterstützten Piperichtlinien.

Hinweis

Die in der Tabelle beschriebenen Richtlinien sind nur für die angegebenen Endpunkte gültig. Das Festlegen der Richtlinie für andere Endpunkte hat keine Auswirkungen auf das Verhalten von WinUSB für Lese- oder Schreibanforderungen.

Richtliniennummer Richtlinienname BESCHREIBUNG Endpunkt (Richtung) Standardwert
0x01 SHORT_PACKET_TERMINATE Sendet ein Paket der Länge null für eine Schreibanforderung, bei der der Puffer ein Vielfaches der maximalen Paketgröße ist, die vom Endpunkt unterstützt wird. Bulk (OUT)

Interrupt (OUT)		 false
0x02 AUTO_CLEAR_STALL Löscht eine verzögerte Pipe automatisch, ohne den Datenfluss zu beenden. Bulk (IN)

Interrupt (IN)		 false
0x03 PIPE_TRANSFER_TIMEOUT Wartet auf ein Timeoutintervall in Millisekunden, bevor die Anforderung abgebrochen wird. Bulk (IN)

Bulk (OUT)

Interrupt (IN)

Interrupt (OUT)		 5 Sekunden (5000 Millisekunden) für die Steuerung; 0 für andere
0x04 IGNORE_SHORT_PACKETS Schließt eine Leseanforderung ab, wenn ein kurzes Paket empfangen oder eine bestimmte Anzahl von Bytes gelesen wird. Wenn die Dateigröße unbekannt ist, wird die Anforderung mit einem kurzen Paket beendet. Bulk (IN)

Interrupt (IN)		 FALSE
0x05 ALLOW_PARTIAL_READS Ermöglicht Leseanforderungen von einem Gerät, das mehr Daten zurückgibt als vom Aufrufer angefordert. Bulk (IN)

Interrupt (IN)		 true
0x06 AUTO_FLUSH Speichert die überschüssigen Daten aus der Leseanforderung und fügt sie der nächsten Leseanforderung hinzu oder verwirft die überschüssigen Daten. Bulk (IN)

Interrupt (IN)		 false
0x07 RAW_IO Umgeht Warteschlangen- und Fehlerbehandlung, um die Leistung für mehrere Leseanforderungen zu steigern. Bulk (IN)

Interrupt (IN)		 false
0x08 MAXIMUM_TRANSFER_SIZE Ruft die maximale Größe einer USB-Übertragung ab, die von WinUSB unterstützt wird. Dies ist eine schreibgeschützte Richtlinie, die durch Aufrufen WinUsb_GetPipePolicy abgerufen werden kann. Bulk (IN)

Bulk (OUT)

Interrupt (IN)

Interrupt (OUT)
0x09 RESET_PIPE_ON_RESUME Setzt die Pipe des Endpunkts zurück, nachdem das Anhalten fortgesetzt wurde, bevor neue Anforderungen akzeptiert werden. Bulk (IN)

Bulk (OUT)

Interrupt (IN)

Interrupt (OUT)		 false

Die folgende Tabelle enthält bewährte Methoden für die Verwendung der einzelnen Piperichtlinien und beschreibt das resultierende Verhalten, wenn die Richtlinie aktiviert ist.

Policy Aktivieren, wenn... Verhalten
SHORT_PACKET_TERMINATE(0x01) Das Gerät erfordert, dass die OUT-Übertragungen mit einem Paket der Länge null beendet werden. Die meisten Geräte haben diese Anforderung nicht. Wenn aktiviert ist (der Richtlinienparameterwert ist TRUE oder nonzero), wird jeder Schreibanforderung, die ein Vielfaches der vom Endpunkt unterstützten maximalen Paketgröße entspricht, ein Paket der Länge null gefolgt.

Nach dem Senden von Daten an den Hostcontroller sendet WinUSB eine Schreibanforderung mit einem Paket der Länge null und schließt dann die Anforderung ab, die von WinUsb_WritePipe erstellt wurde.
AUTO_CLEAR_STALL Sie möchten nicht, dass die fehlerhaften Übertragungen den Endpunkt in einem verzögerten Zustand belassen. Diese Richtlinie ist nur nützlich, wenn Sie mehrere ausstehende Leseanforderungen an den Endpunkt haben, wenn RAW_IO deaktiviert ist.
  • Wenn aktiviert ist (der Wert des Richtlinienparameters ist TRUE oder nonzero), wird eine Einstellungsbedingung automatisch gelöscht. Dieser Richtlinienparameter wirkt sich nicht auf Steuerungspipes aus.

    Wenn bei einer Leseanforderung ein Fehler auftritt und der Hostcontroller einen anderen status als STATUS_CANCELLED oder STATUS_DEVICE_NOT_CONNECTED zurückgibt, setzt WinUSB die Pipe zurück, bevor die fehlerhafte Anforderung abgeschlossen wird. Beim Zurücksetzen der Pipe wird die Zustandsunterbrechung gelöscht, ohne den Datenfluss zu unterbrechen. Daten fließen weiterhin in den Endpunkten, solange immer neue Übertragungen vom Gerät eintreffen. Eine neue Übertragung kann eine Übertragung enthalten, die sich in der Warteschlange befand, als der Stillstand aufgetreten ist.

    Das Aktivieren dieser Richtlinie wirkt sich nicht wesentlich auf die Leistung aus.

  • Wenn deaktiviert (Der Richtlinienparameterwert ist FALSE oder Null), schlagen alle Übertragungen, die nach der verzögerten Übertragung an den Endpunkt eintreffen, fehl, bis der Aufrufer die Pipe des Endpunkts manuell zurücksetzt, indem WinUsb_ResetPipe aufgerufen wird.
PIPE_TRANSFER_TIMEOUT Sie erwarten, dass Übertragungen an einen Endpunkt innerhalb einer bestimmten Zeit abgeschlossen werden.
  • Bei Festlegung auf 0 (Standard) wird bei Übertragungen kein Timeout ausgeführt, da der Hostcontroller die Übertragung nicht abbricht. In diesem Fall wartet die Übertragung auf unbestimmte Zeit, bis sie manuell abgebrochen wird oder die Übertragung normal abgeschlossen wird.
  • Wenn auf einen Wert ohne Wert (Timeoutintervall) festgelegt ist, startet der Hostcontroller einen Timer, wenn er die Übertragungsanforderung empfängt. Wenn der Timer das festgelegte Timeoutintervall überschreitet, wird die Anforderung abgebrochen.

    Aufgrund der Zeitgeberverwaltung tritt eine geringfügige Leistungsstrafe auf.

    Beim Warten in einer WinUSB-Warteschlange gibt es für Anforderungen kein Timeout.

    In Windows Vista stellt WinUSB für alle Übertragungen (mit Ausnahme von Übertragungen mit aktiviertem RAW_IO) die Anforderung in die Warteschlange, bis alle vorherigen Übertragungen auf dem Zielendpunkt abgeschlossen wurden. Der Hostcontroller schließt die Warteschlangenzeit nicht in die Berechnung des Timeoutintervalls ein.

    Wenn RAW_IO aktiviert ist, stellt WinUSB die Anforderung nicht in die Warteschlange. Stattdessen übergibt er die Anforderung direkt an den USB-Stapel, unabhängig davon, ob der USB-Stapel mit der Verarbeitung früherer Übertragungen beschäftigt ist. Wenn der USB-Stapel ausgelastet ist, kann die Verarbeitung der neuen Anforderung verzögert werden. Dies kann zu einem Timeout führen.
IGNORE_SHORT_PACKETS RAW_IO ist deaktiviert, und Sie möchten nicht, dass kurze Pakete die Leseanforderungen abschließen.
  • Wenn aktiviert ist (der Richtlinienparameterwert ist TRUE oder nonzero), schließt der Hostcontroller keinen Lesevorgang sofort ab, nachdem er ein kurzes Paket empfangen hat. Stattdessen wird der Vorgang nur abgeschlossen, wenn:
    • Ein Fehler tritt auf.
    • Die Anforderung wird abgebrochen.
    • Alle angeforderten Bytes wurden empfangen.
  • Wenn deaktiviert ist (der Richtlinienparameterwert ist FALSE oder Null), schließt der Hostcontroller einen Lesevorgang ab, nachdem er die angeforderte Anzahl von Bytes gelesen oder ein kurzes Paket empfangen hat.
ALLOW_PARTIAL_READS Das Gerät kann mehr Daten als angefordert senden, wenn die Größe Ihres Anforderungspuffers ein Vielfaches der maximalen Endpunktpaketgröße beträgt.

Verwenden Sie, wenn Ihre Anwendung einige Bytes lesen möchte, um zu bestimmen, wie viele Bytes insgesamt gelesen werden sollen.
  • Wenn deaktiviert (Der Richtlinienparameterwert ist FALSE oder Null) und das Gerät mehr Daten als angefordert zurückgibt, schließt WinUSB die Anforderung mit einem Fehler ab.
  • Wenn aktiviert ist (Der Richtlinienparameterwert ist TRUE oder nonzero) und das Gerät mehr Daten als angefordert zurückgibt, kann WinUSB (abhängig von AUTO_FLUSH Einstellungen) die überschüssigen Daten aus der Leseanforderung am Anfang der nächsten Leseanforderung hinzufügen oder die überschüssigen Daten verwerfen.

    Wenn diese Option aktiviert ist, schließt WinUSB Leseanforderungen für null Bytes sofort erfolgreich ab und sendet die Anforderungen nicht nach unten im Stapel.
AUTO_FLUSH ALLOW_PARTIAL_READS Richtlinie ist aktiviert.

Das Gerät kann mehr Daten als angefordert senden, und Ihre Anwendung benötigt keine anderen Daten. Dies ist möglich, wenn die Größe Ihres Anforderungspuffers ein Vielfaches der maximalen Endpunktpaketgröße beträgt.		 AUTO_FLUSH definiert das Verhalten von WinUSB, wenn ALLOW_PARTIAL_READS aktiviert ist. Wenn ALLOW_PARTIAL_READS deaktiviert ist, wird der AUTO_FLUSH Wert von WinUSB ignoriert.

WinUSB kann entweder die restlichen Daten verwerfen oder mit der nächsten Leseanforderung des Aufrufers senden.

  • Wenn aktiviert ist (der Richtlinienparameterwert ist TRUE oder nonzero), verwirft WinUSB die zusätzlichen Bytes ohne Fehlercode.
  • Wenn deaktiviert ist (der Richtlinienparameterwert ist FALSE oder Null), speichert WinUSB die zusätzlichen Bytes, fügt sie dem Anfang der nächsten Leseanforderung des Aufrufers hinzu und sendet die Daten dann im nächsten Lesevorgang an den Aufrufer.
RAW_IO Die Leistung ist eine Priorität, und die Anwendung sendet gleichzeitig Leseanforderungen an denselben Endpunkt.

RAW_IO erzwingt bestimmte Einschränkungen für den Puffer, der vom Aufrufer in WinUsb_ReadPipe übergeben wird:

  • Die Pufferlänge muss ein Vielfaches der maximalen Endpunktpaketgröße sein.
  • Die Länge muss kleiner oder gleich dem Wert von MAXIMUM_TRANSFER_SIZE sein, die von WinUsb_GetPipePolicy abgerufen werden.
 Wenn diese Option aktiviert ist, werden Warteschlangen und Fehlerbehandlung umgangen, um die Leistung für mehrere Leseanforderungen zu steigern. WinUSB verarbeitet Leseanforderungen wie folgt:

  • Eine Anforderung, die kein Vielfaches der maximalen Endpunktpaketgröße ist, schlägt fehl.
  • Eine Anforderung, die größer als die von WinUSB unterstützte maximale Übertragungsgröße ist, schlägt fehl.
  • Alle wohlgeformten Anforderungen werden sofort an den USB-Kernstapel gesendet, um im Hostcontroller geplant zu werden.


Das Aktivieren dieser Einstellung verbessert die Leistung mehrerer Leseanforderungen erheblich, indem die Verzögerung zwischen dem letzten Paket einer Übertragung und dem ersten Paket der nächsten Übertragung verringert wird.
RESET_PIPE_ON_RESUME Das Gerät behält seinen Dateneinschaltzustand über das Anhalten nicht bei. Beim Fortsetzen vom Anhalten setzt WinUSB den Endpunkt zurück, bevor der Aufrufer neue Anforderungen an den Endpunkt senden kann.