Die API zum USB2LPT (Anwendungsprogrammierer-Schnittstelle)

Weil aber das Abfangen und Umleiten von Portzugriffen wegen der Paketorientierung von USB über eine bestimmte Geschwindigkeit nicht hinauskommt, erscheint eine API für neue, spezialisierte Programme dennoch sinnvoll.

Die Strategie ist einfach und erfordert keine zusätzlichen DLLs: Öffnen Sie mit CreateFile das Gerät "\\.\LPT1" (oder "LPT2" wenn es das zweite Gerät ist usw.), und schicken/holen die zu transferierenden Daten über möglichst wenige Aufrufe von DeviceIoControl.

Parallelport-kompatibler Portzugriff

Öffnen von USB2LPT

HANDLE hAccess;

 for (int n=9; n; n--) {	// von hinten probieren
  TCHAR DevName[12];
  wsprintf(DevName,"\\\\.\\LPT%u",sn);
  hAccess=CreateFile(DevName,
   GENERIC_READ|GENERIC_WRITE,0,NULL,OPEN_EXISTING,0,0);
  if (hAccess!=INVALID_HANDLE_VALUE) goto found;
 }
 hAccess=0;
found:

// Den 8051 XRAM oder ATmega Flash-Speicher ab Adresse 6 auslesen, wo das Firmware-Datum steht.
// Klappt das nicht, ist's kein USB2LPT.
#include "usb2lpt.h"
 WORD addr = 6;
 WORD date = 0;		// FAT-Datumsstempel
 DWORD BytesRet;
 if (DeviceIoControl(hAccess,IOCTL_VLPT_XramRead/*0x22228E*/,&adr,sizeof(adr),&date,sizeof(date),&BytesRet,NULL)) {
  // dies ist tatsächlich ein USB2LPT, und man das Datum wie folgt zur Anzeige bringen:
   FILETIME ft;
   DosDateTimeToFileTime(date,0,&ft);
   SYSTEMTIME st;
   FileTimeToSystemTime(&ft,&st);
   TCHAR s[20];		// In diesen Zeichenpuffer kommt das landestypisch formatierte Datum
   GetDateFormat(LOCALE_USER_DEFAULT,0,&st,NULL,s,20);
   // ...
 }else{
  // dies ist ein Standard-Parallelport oder irgendetwas anderes
 }

Einzelner OUT-Zugriff

void outb(BYTE a, BYTE b) {
 BYTE IoData[2];
 DWORD BytesRet;
 IoData[0]=a;
 IoData[1]=b;
 DeviceIoControl(hAccess,
   CTL_CODE(FILE_DEVICE_UNKNOWN,0x804,METHOD_BUFFERED,FILE_ANY_ACCESS),	//0x222010
   IoData,sizeof IoData,NULL,0,&BytesRet,NULL);
}

• 0 = Datenport (siehe Beyond Logic)
• 2 = Steuerport (mit den Bits „Strobe“, „AutoFeed“, aber auch „Direction“ = Richtungswahl für Datenport)
  
• 3 = EPP-Adress-Schreib-Zyklus (siehe Beyond Logic)
• 4 = EPP-Daten-Schreib-Zyklus (a = 5, 6 und 7 machen ebenfalls EPP-Datenzyklen)

• 8 = ECP-FIFO schreiben (siehe Beyond Logic)
• 10 = ECP-Konfigurationsregister „ECR“ setzen

Einzelner IN-Zugriff

BYTE inb(BYTE a) {
 BYTE IoData[1];
 DWORD BytesRet;
 IoData[0]=a|0x10;	// Lese-Bit
 DeviceIoControl(hAccess,
   CTL_CODE(FILE_DEVICE_UNKNOWN,0x804,METHOD_BUFFERED,FILE_ANY_ACCESS),
   IoData,sizeof(IoData),IoData,sizeof(IoData),&BytesRet,NULL);
 return IoData[0];
}

• 0 = Datenport
• 1 = Statusport (mit den Bits „Busy“, „Acknowledge“, „Paper End“ usw.)
• 2 = Steuerport (tatsächliche Leitungspegel)
  
• 3 = EPP-Adress-Lese-Zyklus (siehe Beyond Logic)
• 4 = EPP-Daten-Lese-Zyklus (a = 5, 6 und 7 machen ebenfalls EPP-Datenzyklen)
• 8 = ECP-FIFO lesen oder „Konfigurationsregister A“ lesen
• 9 = „Konfigurationsregister B“ lesen (stets 0)
• 10 = ECP-Konfigurationsregister „ECR“ (bspw. FIFO-Zustand) lesen

Es gibt hierzu eine einfache DLL-Implementierung als — gewissermaßen — vorläufige Referenzimplementierung.

Kombinierte Zugriffe

Sieht man sich die Programmstücke genauer an, sieht man, dass alles über Ein- und Ausgabepuffer eines IOCTL-Kodes (0x222010) abgewickelt wird. Das ist kombinierfähig bis zu beliebigen Puffergrößen. Eine sinnvolle Obergrenze sind 64 Bytes, so ist es auch im Treiber realisiert.

Die Kombination von Zugriffen erfolgt durch das Hintereinanderschreiben von OUT-Adressen und OUT-Daten sowie IN-Adressen im Eingabepuffer. IN-Adressen sind das gleiche wie OUT-Adressen mit gesetztem Bit 4. Und: Für jede IN-Adresse benötigt man im Ausgabepuffer 1 Byte Platz. Das ist alles! Also eine Art Mikrocode für die USB2LPT-Firmware.

Beispielsweise:

// Lesen aller 17 Portpins in einem Rutsch
void GetPinStates(BYTE states[3]) {
 static const BYTE SendBytes[3]={0x10,0x11,0x12};
 DWORD BytesRet;
 DeviceIoControl(hAccess,
   CTL_CODE(FILE_DEVICE_UNKNOWN,0x804,METHOD_BUFFERED,FILE_ANY_ACCESS),
   SendBytes,3,states,3,&BytesRet,NULL);
}

Erweiterter Portzugriff

Die entsprechende Hintertür sind vor allem weitere Adressen:

• 12 = Richtungsregister Datenport (Standard: 0xFF)
• 13 = Richtungsregister Statusport (Standard: 0x07)
• 14 = Richtungsregister Steuerport (Standard: 0x0F)
• 15 = USB2LPT-Feature-Register (Standard: 0x00, bei High-Speed 0x24)

Die noch verbleibende Adresse 11 ist nicht belegt.

Die Feature-Register-Bits:

0. Offene-Senke-Simulation für Datenport (+0)
1. Offene-Senke-Simulation für Steuerport (+2) in Betriebsart SPP
2. Offene-Senke-Simulation für Steuerport (+2) in allen anderen Betriebsarten
3. ungenutzt
4. Serialized: USB-Gerät gibt sich mit Seriennummer aus. Daher eineindeutige Zuordnung auch bei wechselnden USB-Topologien.
5. DarkBlue: dunklere blaue LED mittels Pulsweitenmodulation (nur High-Speed-Versionen, Tastverhältnis 12,5 %)
6. DirectIO (keine Invertierungen; Zugang zu Bits 0..2 des Statusports)
7. • PullUps: Deaktivierung der Pullups (nur High-Speed-Versionen)
   • UseBulk: Bulk-Transfers statt Interrupt (nur Low-Speed-Versionen)
     Bulk-Transfers sind 8x schneller, aber nur bis Windows XP erlaubt! Bei Vista und neuer wird ein solches USB-Gerät nicht mehr erkannt! Dieses Bit kann folglich nur unter XP und älter zurückgesetzt werden, um USB2LPT (Low-Speed) unter Vista und neuer zu verwenden.

Nur High-Speed und Full-Speed: Durch Offene-Senke-Simulation wird der 5-V-Spannungspegel für HIGH-Ausgänge erreicht. Ansonsten werden nur maximal 3,3 V ausgegeben, was für manche Hardware nicht ausreichen könnte.

Nur Low-Speed: Da hier nur schwache interne Pullup-Widerstände vorhanden sind (Richtwert 40 kΩ), ist hierbei die Offene-Senke-Simulation mit Vorsicht zu verwenden (in der Regel mit externem Pull-Up-Widerstand).
Der HIGH-Ausgangspegel liegt bei 5 V. Falls 3,3 V gewünscht sind, muss dass USB2LPT-Gerät modifiziert werden, durch Einsetzen einer Betriebsspannung reduzierenden Doppeldiode BAV199 bei D2 (Brücke SJ3) durchkratzen, und Ersatz von R1 durch 1,5 kΩ. Siehe Schaltplan.

Wartezyklen und Bitoperationen

• 0x20 = warten, danach Wartezeit in 4-µs-Schritten, 0 = 1024 µs
• 0x21 = Einzelbit setzen, danach Bitadresse*
• 0x22 = Einzelbit löschen, danach Bitadresse*
• 0x23 = Einzelbit kippen, danach Bitadresse*
• 0x24 = warten auf Pegel, danach Bitadresse:
  • Bit 7:4 = Port-Offset, 0 = Datenport, 1 = Statusport, 2 = Steuerport usw.
  • Bit 3 (bei Bit-Warten) = Prüfzustand: 0 = Weiter wenn Bit 0 (blockiere solange Bit 1), 1 = Weiter wenn Bit 1 (blockiere solange Bit 0)
  • Bit 3 (bei Einzelbitoperationen): 0 = normale LPT-Emulation (Lesen vom Eingaberegister), 1 = Stuck-sichere Operation (Lesen vom Ausgaberegister)
  • Bit 2:0 = Bitnummer 0..7 (beim Steuerport lesen liefert 4..7 undefinierte Zustände, bspw. von einer LED!)
  Dieser Opcode dient insbesondere zur Implementierung von I²C. Die Blockierzeit ist maximal 1024 µs, dann geht es mit dem nächsten Mikrocode-Befehl weiter.

Die Sonderadresse 0x24 ist noch nicht implementiert.

Nicht geplant: Peripherienutzung (Timer u.ä.)

Lesen und Schreiben des RAM, EEPROM oder Flash-Speichers

Der Zugriff ist derselbe wie bei Cypress' ezusb.sys und geladenem vend_ax.hex. Dabei macht man sich eine un(ter)dokumentierte Eigenart von Windows' DeviceIoControl() zu Nutze: Ist im Gerätesteuerkode METHOD_IN_DIRECT gesetzt, fungiert lpOutBuffer als weiterer Eingabepuffer. Dieser enthält schließlich die Nutzdaten für die Control-Transfer-Datenphase. lpInBuffer zeigt nur auf den Wert von wValue (wenn nInBufferSize==2, wIndex ist dann Null) oder auf die Werte von wValue und wIndex (wenn nInBufferSize==4).

Es sind belegt:

EEPROM-Inhalt

Da die EEPROMs allesamt mit unvollständiger Adressdekodierung arbeiten, gelangt man mit den hohen Adressen automatisch ans EEPROM-Ende, unabhängig von der jeweiligen EEPROM-Größe.

Die USB-Schnittstelle

Dieser Abschnitt ist für die Implementierung von Treibern relevant. Also insbesondere für Nicht-Windows-Systeme. Oder auch zum Nachbau von USB-Geräten mit anderen Mikrocontrollern. Grundlegend ist die Übermittlung von „Mikrocode“, die Übertragung von Adressen und Datenbytes, genauso wie oben beschrieben. Im einfachsten Fall zwei Bytes für einen OUT-Befehl sowie ein Byte für einen IN-Befehl, gefolgt vom Abfragen des IN-Datenbytes.

Für neuere Firmware-Implementierungen (ab 2009) gilt: Das OUT-Datenbyte zu einem OUT-Adressbyte darf sich in einem nachfolgenden Transfer befinden. Ansonsten müssen sich OUT-Adresse und zugehöriges OUT-Datenbyte stets in einem USB-Transfer-Block befinden.

Für Full-Speed- und High-Speed-USB2LPT gilt: Es existiert Doppel-Pufferung für USB-OUT und USB-IN-Bulk-Transfers. Daher darf man bis zu 3 USB-OUT-Blöcke senden, bevor man die Ergebnisse (in ebenso vielen Blöcken) abholen muss.
In allen anderen Fällen gilt: Der USB-IN-Transfer-Block muss sich dem USB-OUT-Transfer-Block anschließen (keine Schachtelung erlaubt).

USB2LPT bietet (bis zu) 4 Möglichkeiten zu deren Übertragung. Ein gemischter Zugriff (bspw. Senden des Mikrocodes nach Methode 1 und Lesen der IN-Datenbytes nach Methode 2) ist nicht vorgesehen und dessen Funktion implementationsabhängig.

Hersteller-spezifische (also haftmann#software-erdachte) Bulk-Pipes (seit 2004)

Diese Schnittstelle ist auf minimalem Overhead ausgelegt. Sie ist die ursprüngliche Schnittstelle.

Unter der USB-Adresse mit VID = 0x16C0, PID = 0x06B3 .. 0x06B6 und dem Interface 0 bietet USB2LPT zwei Bulk-Pipes zum direkten Mikrocode-Transfer an.

0. Bulk-Out für (OUT-Adresse+OUT-Datenbyte) und/oder (IN-Adresse)
1. Bulk-In für (IN-Datenbyte)

• Bulk Out (Länge je nach Daten)
  n Bytes Mikrocode

  Mikrocode ausgeben, n = 1..8/64/512

• Bulk In (Länge je nach Daten)
  n IN-Datenbytes

  Get Input Report (Datenbytes lesen), n = 1..8/64/512

Bei Low-Speed (seit 2007) gibt es hierbei zwei Alternate Settings:

0. Zwei Bulk-Pipes (laut USB-Standard verboten, funktioniert jedoch unter Win98,Me,2k,XP)
1. Zwei Interrupt-Pipes mit bInterval = 10 (bewirkt um Faktor 8 höhere Latenzzeit — der Windows-Treiber schaltet unter Windows Vista und Windows 7 automatisch auf diese Alternate Setting.)

• Low-Speed: 8 Bytes
• Full-Speed: 64 Bytes
• High-Speed: 512 Bytes

Windows stückelt zu lange Transferpuffer selbständig in FIFO-Häppchen! Die maximale Blockgröße unter Windows ist typisch 4 KByte.

Bei Umschaltung auf GPIF-Transfers (nur High-speed-fähige USB2LPT Rev. 2,3,4,7) erfolgt über diese beiden Bulk-Pipes der High-Speed-Datenstrom mit bis zu 48 MByte/s (Burst, praktisch maximal 20 MByte/s). Bei Full-Speed sind's maximal 0,8 MByte/s, ohne GPIF, aber mit schneller 8-Bit-FIFO, ähnlich FT245. Eine genauere Spezifikation werde ich erst bei Bedarf erarbeiten und implementieren; insbesondere wie dieser Modus aktiviert und wieder deaktiviert wird.

Bei Fehlsteuerung antwortet die BULK- bzw. INTERRUPT-Pipe mit STALL:

• Fehlerhafter Mikrocode (Befehlsbyte > 0x20) → STALL auf OUT-Pipe
• Falsche Länge beim Abholen der Daten → STALL auf IN-Pipe (nicht implementiert!)

Das Konzept mit den beiden BULK-Pipes ist einer gewöhnlichen seriellen oder TCP-Verbindung entlehnt und lässt sich daher mühelos auf eine serielle Schnittstelle oder einer Ethernet-Verbindung umsetzen.

Q: Wieviel Bytes Mikrocode kann ich hinschicken, bevor ich Ergebnisbytes abholen muss?

A: Das ist zurzeit nicht definiert. Es kommt auf die Anzahl der Ergebnisbytes an, die irgendwo im Mikrocontroller gepuffert werden müssen. Da der kleinste Controller 512 Bytes RAM aufweist, wird das Limit hiermit (130821) auf 256 Bytes festgelegt. Auf der sicheren Seite liegt man zurzeit bei 7 Bytes, der kleinsten FIFO-Größe im HID-Modus. Erfolgt das Senden und Empfangen gleichzeitig (via DeviceIoControl()) ist die Datenmenge unbegrenzt: Windows und das USB-Protokoll kümmert sich um entsprechende Pufferungen.

Hersteller-spezifische (also haftmann#software-erdachte) Control-Befehle (seit 2009)

Unter der USB-Adresse mit VID = 0x16C0, PID = 0x06B3 .. 0x06B6 und dem Interface 0 kann man USB2LPT folgende vendor-spezifische Befehle schicken:

• bmRequestType	bRequest	wValue	wIndex	wLength		Data Out
  0x40	0x90	0x0000	0x0000	n		n Bytes Mikrocode

  (Für Effizienz sollte n > 4 sein, denn für kürzeren Mikrocode stehen die unteren bRequest-Werte zur Verfügung. Der Puffer für die IN-Datenbytes ist auf 64 Byte begrenzt!)

• bmRequestType	bRequest	wValue	wIndex	wLength		Data In
  0xC0	0x90	0x0000	0x0000	n		n IN-Datenbytes

  (im Anschluss zum Abholen der IN-Datenbytes des vorher gehenden Mikrocodes)

• bmRequestType	bRequest	wValue		wIndex	wLength		Data In
  0xC0	0x91	µCode[0]	0x00	0x0000	0x0001		IN-Datenbyte

  (1 IN-Befehl)

• bmRequestType	bRequest	wValue		wIndex	wLength
  0x40	0x92	µCode[0]	µCode[1]	0x0000	0x0000

  (1 OUT-Befehl)

• bmRequestType	bRequest	wValue		wIndex	wLength		Data In
  0xC0	0x92	µCode[0]	µCode[1]	0x0000	0x0002		2 IN-Datenbytes

  (2 IN-Befehle)

• bmRequestType	bRequest	wValue		wIndex		wLength		Data In
  0xC0*	0x93	µCode[0]	µCode[1]	µCode[2]	0x00	n		n IN-Datenbytes

  (mehrere Befehle, zumeist 1 OUT- und 1 IN-Befehl)

• bmRequestType	bRequest	wValue		wIndex		wLength		Data In
  0xC0*	0x94	µCode[0]	µCode[1]	µCode[2]	µCode[3]	n		n IN-Datenbytes

  (mehrere Befehle, bspw. 2 OUT-Befehle)

Für minimale Latenz werden für kurze Mikrocodes die vier „freien“ Bytes des Setup-Transfers mit Nutzdaten gefüllt. Das ist der Trick.

Mikrocode darf auch im Block unvollständig übertragen werden, dann wird dieser mit dem nächsten Transfer fortgesetzt. Beispiel:

• 1. Transfer: 1 Byte „0x00“ (Kode für „Ausgabe Datenport“)
• 2. Transfer: 1 Byte „0x42“ (das zugehörige Datenbyte)

Bei Fehlsteuerung antwortet der SETUP-Transfer mit STALL:

• Fehlerhafter Mikrocode (Befehlsbyte > 0x20)
• Überlauf des internen Datenpuffers

HID-Interface mit Input- und Output-Report (nicht bei Low-Speed; ab 2011)

Beide Reports sind gleichartig aufgebaut:

• 0: Report-ID = 8 (?)
• 1: Anzahl Nutzbytes n des Reports (n = 0 .. 62)
• 2..63: n Nutzbytes, danach irgendwelche Dummy-Bytes

• Interrupt Out (stets 64 Bytes lang)
  0x08	n	n Bytes Mikrocode	ungenutzt

  Set Output Report (Mikrocode ausgeben), n = 0..62

• Interrupt In (stets 64 Bytes lang)
  0x08	n	n IN-Datenbytes	ungenutzt

  Get Input Report (Datenbytes lesen), n = 0..62

Der Report-Deskriptor des Low-Speed-USB2LPT bietet keine Input- und Output-Reports, danach lässt sich eine Fallunterscheidung machen.

Seit September 2011 ist der HID-Report-Deskriptor so gestaltet, dass sich dieser mit den HidP-Funktionen vernünftig enumerieren lässt. Im wesentlichen wurden verschiedene Dummy-Usages zugeordnet.

HID-Interface mit Feature-Reports (seit 2010)

Der Feature-Report überträgt per Feature-Out den Mikrocode und per Feature-In die IN-Datenbytes. Er ist wie folgt aufgebaut:

• 0: Anzahl Nutzbytes n des Reports, gleichzeitig Report-ID (n = 1 .. 7)
• 1..7: n Nutzbytes

• bmRequestType	bRequest	wValue		wIndex		wLength		Data Out
  0x21	0x09	n	0x03	Interface	0x00	n+1		n	n Bytes Mikrocode

  Set Feature Report (Mikrocode ausgeben), n = 1..7, Interface = Nummer im Multifunktionsgerät

• bmRequestType	bRequest	wValue		wIndex		wLength		Data In
  0xA1	0x01	n	0x03	Interface	0x00	n+1		n	n IN-Datenbytes

  Get Feature Report (Datenbytes lesen), n = 1..7, Interface = Nummer im Multifunktionsgerät

Diese Übertragungsart soll auch bei Full-Speed und High-Speed verfügbar sein, ist jedoch dort ungetestet.

Seit September 2011 ist der HID-Report-Deskriptor so gestaltet, dass sich dieser mit den HidP-Funktionen vernünftig enumerieren lässt. Im wesentlichen wurden verschiedene Dummy-Usages zugeordnet. Dies kann man mit dem Programm hidparse auflisten.