WinUSB-Funktionen für Änderungen an Piperichtlinien

  • Artikel

Um Anwendungen das Abrufen und Festlegen der Standardrichtlinienparameter einer Endpunktpipeline zu ermöglichen, macht Winusb.dll die WinUsb_GetPipePolicy-Funktion verfügbar, um die Standardrichtlinie der Pipe abzurufen. Mit der WinUsb_SetPipePolicy-Funktion kann eine Anwendung den Richtlinienparameter auf einen neuen Wert festlegen.

Mit WinUSB können Sie das Standardverhalten ändern, indem Sie Richtlinien auf die Pipeline eines Endpunkts anwenden. Mithilfe dieser Richtlinien können Sie WinUSB so konfigurieren, dass es Ihrem Gerät am besten mit seinen Funktionen übereinstimmt. Die folgende Tabelle enthält eine Liste der pipe-Richtlinien, die von WinUSB unterstützt werden.

Hinweis

Die in der Tabelle beschriebenen Richtlinien sind nur für die angegebenen Endpunkte gültig. Das Festlegen der Richtlinie auf anderen Endpunkten 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, in der der Puffer ein Vielfaches der maximalen Paketgröße ist, die vom Endpunkt unterstützt wird. Massenvorgang (OUT)

Interrupt (OUT)		 FALSE
0x02 AUTO_CLEAR_STALL Löscht automatisch ein hängendes Rohr, ohne den Datenfluss zu stoppen. Massenvorgang (IN)

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

Massenvorgang (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 wird oder eine bestimmte Anzahl von Bytes gelesen wird. Wenn die Dateigröße unbekannt ist, wird die Anforderung bei einem kurzen Paket beendet. Massenvorgang (IN)

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

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

Interrupt (IN)		 FALSE
0x07 RAW_IO Umgehen Sie die Warteschlangen- und Fehlerbehandlung, um die Leistung für mehrere Leseanforderungen zu steigern. Massenvorgang (IN)

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

Massenvorgang (OUT)

Interrupt (IN)

Interrupt (OUT)
0x09 RESET_PIPE_ON_RESUME Setzt die Pipe des Endpunkts nach dem Fortsetzen des Anhaltens zurück, bevor neue Anforderungen akzeptiert werden. Massenvorgang (IN)

Massenvorgang (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... Behavior
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 (Der Wert des Richtlinienparameters ist WAHR oder ungleich Null), wird auf jede Schreibanforderung, die ein Vielfaches der vom Endpunkt unterstützten maximalen Paketgröße ist, auf ein Paket mit der Länge Null folgt.

Nach dem Senden von Daten an den Hostcontroller sendet WinUSB eine Schreibanforderung mit einem Paket mit null Länge und schließt dann die Anforderung ab, die von WinUsb_WritePipe erstellt wurde.
AUTO_CLEAR_STALL Sie möchten nicht, dass die fehlgeschlagenen Übertragungen den Endpunkt in einem verzögerten Zustand verlassen. Diese Richtlinie ist nur hilfreich, wenn mehrere ausstehende Leseanforderungen an den Endpunkt vorhanden sind, wenn RAW_IO deaktiviert ist.
  • Wenn aktiviert (Der Richtlinienparameterwert ist TRUE oder nonzero), wird automatisch eine Ständebedingung gelöscht. Dieser Richtlinienparameter wirkt sich nicht auf Steuerrohre aus.

    Wenn eine Leseanforderung fehlschlägt und der Hostcontroller einen anderen Status als STATUS_CANCELLED oder STATUS_DEVICE_NOT_CONNECTED zurückgibt, setzt WinUSB die Pipe zurück, bevor die fehlgeschlagene Anforderung abgeschlossen wird. Durch das Zurücksetzen des Rohrs wird der Zustand der Stände gelöscht, ohne den Datenfluss zu unterbrechen. Daten fließen weiterhin in den Endpunkten, solange neue Übertragungen weiterhin vom Gerät empfangen werden. Eine neue Übertragung kann eine übertragung enthalten, die sich in der Warteschleife befand, als der Stand aufgetreten ist.

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

  • Wenn deaktiviert (Richtlinienparameterwert ist FALSE oder Null), schlagen alle Übertragungen, die nach der verzögerten Übertragung an den Endpunkt gelangen, fehl, bis der Aufrufer die Endpunktpipeline manuell zurücksetzt, indem WinUsb_ResetPipe aufgerufen wird.
PIPE_TRANSFER_TIMEOUT Sie erwarten, dass Übertragungen an einen Endpunkt innerhalb eines bestimmten Zeitraums abgeschlossen werden.
  • Bei Festlegung auf Null (Standard) wird kein Timeout für Übertragungen 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 ist.
  • Bei Festlegung auf einen Wert ungleich Null (Timeoutintervall) 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 Leistungseinbuße auf.

    Anforderungen timeout beim Warten in einer WinUSB-Warteschlange nicht.

    In Windows Vista werden für alle Übertragungen (mit Ausnahme von Übertragungen mit aktivierter RAW_IO) winUSB die Anforderung in die Warteschlange gestellt, bis alle vorherigen Übertragungen am Zielendpunkt abgeschlossen wurden. Der Hostcontroller enthält die Warteschlangenzeit nicht in die Berechnung des Timeoutintervalls.

    Wenn RAW_IO aktiviert ist, wird die Anforderung von WinUSB nicht in die Warteschlange gestellt. Stattdessen übergibt sie die Anforderung direkt an den USB-Stapel, 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 deaktiviert ist und Sie nicht möchten, dass kurze Pakete die Leseanforderungen ausführen.
  • Wenn aktiviert (Der Richtlinienparameterwert ist TRUE oder nicht null), schließt der Hostcontroller einen Lesevorgang nicht unmittelbar nach dem Empfangen eines kurzen Pakets ab. Stattdessen wird der Vorgang nur abgeschlossen, wenn:
    • Ein Fehler tritt auf.
    • Die Anforderung wird abgebrochen.
    • Alle angeforderten Bytes wurden empfangen.
  • Wenn deaktiviert (Der Wert des Richtlinienparameters ist FALSE oder Null), schließt der Hostcontroller einen Lesevorgang ab, nachdem er die angeforderte Anzahl von Bytes gelesen hat oder ein kurzes Paket empfangen hat.
ALLOW_PARTIAL_READS Das Gerät kann mehr Daten senden als angefordert, wenn die Größe des Anforderungspuffers ein Vielfaches der maximalen Endpunktpaketgröße ist.

Verwenden Sie diese Eigenschaft, wenn Ihre Anwendung einige Bytes lesen möchte, um zu bestimmen, wie viele Bytes insgesamt gelesen werden sollen.
  • Wenn deaktiviert (Richtlinienparameterwert ist FALSE oder Null) und das Gerät mehr Daten zurückgibt, als angefordert wurde, schließt WinUSB die Anforderung mit einem Fehler ab.
  • Wenn aktiviert (Richtlinienparameterwert ist WAHR oder ungleich Null) und das Gerät mehr Daten zurückgibt, als angefordert wurden, kann WinUSB (abhängig von AUTO_FLUSH Einstellungen) die überzähligen 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 sofort Leseanforderungen für null Bytes erfolgreich ab und sendet die Anforderungen nicht nach unten.
AUTO_FLUSH ALLOW_PARTIAL_READS Richtlinie ist aktiviert.

Das Gerät kann mehr Daten senden als angefordert, und Ihre Anwendung erfordert keine anderen Daten. Dies ist möglich, wenn die Größe des Anforderungspuffers ein Vielfaches der maximalen Endpunktpaketgröße ist.		 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 die verbleibenden Daten entweder verwerfen oder mit der nächsten Leseanforderung des Anrufers senden.

  • Wenn aktiviert (Richtlinienparameterwert ist WAHR oder ungleich Null) verwirft WinUSB die zusätzlichen Bytes ohne Fehlercode.
  • Wenn deaktiviert (Richtlinienparameterwert ist FALSE oder Null), speichert WinUSB die zusätzlichen Bytes, fügt sie am 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 gleichzeitige Leseanforderungen an denselben Endpunkt.

RAW_IO legt bestimmte Einschränkungen für den Puffer fest, 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 der von WinUsb_GetPipePolicy abgerufenen MAXIMUM_TRANSFER_SIZE sein.
 Wenn diese Option aktiviert ist, umgehen Übertragungen das Warteschlangen- und Fehlerbehandlungsverhalten, um die Leistung für mehrere Leseanforderungen zu steigern. WinUSB verarbeitet Leseanforderungen wie folgt:

  • Eine Anforderung, bei der es sich nicht um ein Vielfaches der maximalen Paketgröße des Endpunkts handelt, 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, der im Hostcontroller geplant werden soll.


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