Kapitel 25. USB Gerätemodus

25.1. Übersicht

Dieses Kapitel behandelt die Verwendung des USB Gerätemodus und USB On-The-Go (USB OTG) unter FreeBSD. Dazu gehören virtuelle serielle Konsolen, virtuelle Netzwerkkarten und virtuelle USB-Laufwerke.

Wenn die eingesetzte Hardware den USB-Gerätemodus oder USB OTG unterstützt, kann FreeBSDs USB-Stack im Gerätemodus ausgeführt werden. Solche Hardware wird häufig in eingebetteten Systeme verbaut. Der Gerätemodus ermöglicht es dem Rechner verschiedene Arten von USB-Geräteklassen darzustellen, einschließlich serieller Schnittstellen, Netzwerkkarten und Massenspeicher oder Kombinationen davon. Ein USB-Host, beispielsweise ein Notebook oder ein Desktop-Rechner, kann wie auf ein physisches USB-Gerät darauf zugreifen.

Es gibt zwei grundlegende Möglichkeiten, wie die Hardware den Gerätemodus bereitstellen kann: mit einem separaten "Client Modus", der nur den Gerätemodus unterstützt, und mit einem USB-OTG-Port, der sowohl den Geräte- als auch den Hostmodus bereitstellen kann. Bei USB-OTG-Ports wechselt der USB-Stack automatisch zwischen host- und geräteseitig, je nachdem, was an dem Port angeschlossen ist. Wenn Sie ein USB-Gerät wie einen Speicherstick an den Port anschließen, wechselt FreeBSD in den Hostmodus. Wenn Sie einen USB-Host wie einen Computer anschließen, wechselt FreeBSD in den Gerätemodus. "Client Ports" arbeiten immer im Gerätemodus.

Was FreeBSD dem USB-Host präsentiert, hängt von der sysctl-Variable hw.usb.template ab. Einige Vorlagen bieten ein einzelnes Gerät, beispielsweise ein serielles Terminal, andere bieten mehrere, die alle gleichzeitig verwendet werden können. Ein Beispiel ist die Vorlage 10, die ein Massenspeichergerät, eine serielle Konsole und eine Netzwerkkarte bereitstellt. usb_template(4) enthält eine Liste der verfügbaren Werte.

Beachten Sie, dass in einigen Fällen, abhängig von der Hardware und dem Betriebssystem des Hosts, die Änderung an der Konfiguration nur dann bemerkt werden kann, wenn der Host entweder physisch getrennt und wieder verbunden oder gezwungen wird, den USB-Bus auf eine systemspezifische Weise neu zu scannen. Wenn FreeBSD auf dem Host läuft, kann usbconfig(8) reset verwendet werden. Dies muss auch nach dem Laden von usb_template.ko geschehen, wenn der USB-Host bereits an der USB OTG-Buchse angeschlossen war.

Nachdem Sie dieses Kapitel gelesen haben, werden Sie wissen:

  • wie man den USB Gerätemodus unter FreeBSD einrichtet.

  • wie man die virtuelle serielle Schnittstelle unter FreeBSD konfiguriert.

  • wie man sich mit der virtuellen seriellen Schnittstelle von verschiedenen Betriebssystemen aus verbindet.

25.2. Virtuelle serielle USB-Ports

25.2.1. Konfiguration des USB-Gerätemodus für serielle Ports

Die virtuellen seriellen Ports werden durch die Vorlagen 3, 8 und 10 unterstützt. Beachten Sie, dass Vorlage 3 mit Microsoft Windows 10 ohne spezielle Treiber und INF-Dateien funktioinert. Andere Host-Betriebssysteme arbeiten mit allen drei Vorlagen. Die beiden Kernelmodule usb_template(4) und umodem(4) müssen geladen werden.

Um die seriellen Ports im USB-Gerätemodus zu aktivieren, fügen Sie folgenden Zeilen in /etc/ttys hinzu:

ttyU0	"/usr/libexec/getty 3wire"	vt100	onifconsole secure
ttyU1	"/usr/libexec/getty 3wire"    vt100   onifconsole secure

Danach fügen Sie folgende Zeilen in /etc/devd.conf hinzu:

notify 100 {
	match "system"		"DEVFS";
	match "subsystem"	"CDEV";
	match "type"		"CREATE";
	match "cdev"		"ttyU[0-9]+";
	action "/sbin/init q";
};

Laden Sie die Konfiguration neu, falls devd(8) bereits läuft:

# service devd restart

Stellen Sie sicher, dass die notwendigen Module geladen sind und die richtige Vorlage beim Booten gesetzt ist. Fügen Sie dazu folgende Zeilen in /boot/loader.conf ein:

umodem_load="YES"
hw.usb.template=3

Um das Modul zu laden und die Vorlage ohne Neustart zu aktivieren, verwenden Sie:

# kldload umodem
# sysctl hw.usb.template=3

25.2.2. FreeBSD mit der seriellen Schnittstelle im USB-Gerätemodus verbinden

Um eine Verbindung zu einer Karte herzustellen, die so konfiguriert ist, dass sie serielle Ports im USB-Gerätemodus bereitstellt, schließen Sie den USB-Host, beispielsweise einen Laptop, an den USB OTG- oder USB-Client-Port der Karte an. Verwenden Sie pstat -t auf dem Host, um die Terminalzeilen aufzulisten. Am Ende der Liste sollten Sie einen seriellen USB-Anschluss sehen, zum Beispiel "ttyU0". Um die Verbindung zu öffnen, benutzen Sie:

# cu -l /dev/ttyU0

Nach mehrmaligem Drücken der Enter-Taste erscheint ein Anmeldeprompt.

25.2.3. macOS mit der seriellen Schnittstelle im USB-Gerätemodus verbinden

Um eine Verbindung zu einer Karte herzustellen, die so konfiguriert ist, dass sie serielle Ports im USB-Gerätemodus bereitstellt, schließen Sie den USB-Host, beispielsweise einen Laptop, an den USB OTG- oder USB-Client-Port der Karte an. Um die Verbindung zu öffnen, benutzen Sie:

# cu -l /dev/cu.usbmodemFreeBSD1

25.2.4. Linux mit der seriellen Schnittstelle im USB-Gerätemodus verbinden

Um eine Verbindung zu einer Karte herzustellen, die so konfiguriert ist, dass sie serielle Ports im USB-Gerätemodus bereitstellt, schließen Sie den USB-Host, beispielsweise einen Laptop, an den USB OTG- oder USB-Client-Port der Karte an. Um die Verbindung zu öffnen, benutzen Sie:

# minicom -D /dev/ttyACM0

25.2.5. Windows 10 mit der seriellen Schnittstelle im USB-Gerätemodus verbinden

Um eine Verbindung zu einer Karte herzustellen, die so konfiguriert ist, dass sie serielle Ports im USB-Gerätemodus bereitstellt, schließen Sie den USB-Host, beispielsweise einen Laptop, an den USB OTG- oder USB-Client-Port der Karte an. Um die Verbindung zu öffnen, benötigen Sie ein Terminalprogramm mit Unterstützung für serielle Schnittstellen, zum Beispiel PuTTY. Um den von Windows® verwendeten COM-Port zu ermitteln, starten Sie den Geräte-Manager und erweitern Sie "Ports (COM & LPT)". Dort sehen Sie einen Namen wie "USB Serial Sevice (COM4)". Starten Sie das Terminalprogramm Ihrer Wahl, zum Beispiel PuTTY. Im Dialog von PuTTY setzen Sie den "Connection type" auf "Serial" und notieren im Feld "Serial line" den ermittelten COM-Namen. Danach klicken Sie auf "Open".

25.3. Netzwerkkarten im USB-Gerätemodus

Virtuelle Netzwerkkarten werden durch die Vorlagen 1, 8 und 10 unterstützt. Beachten Sie, dass keine dieser Vorlagen mit Windows® funktioniert. Andere Host-Betriebssysteme arbeiten mit allen drei Vorlagen. Die Kernelmodule usb_template(4) und if_cdce(4) müssen geladen sein.

Stellen Sie sicher, dass die notwendigen Module geladen sind und die richtige Vorlage beim Booten gesetzt ist. Fügen Sie dazu folgende Zeilen in /boot/loader.conf ein:

if_cdce_load="YES"
hw.usb.template=1

Um das Modul zu laden und die Vorlage ohne Neustart zu aktivieren, verwenden Sie:

# kldload if_cdce
# sysctl hw.usb.template=1

25.4. Virtuelle USB-Speichergeräte

cfumass(4) ist ein USB-Gerätetreiber, der seit FreeBSD 12.0 verfügbar ist.

Virtuelle Speichergeräte werden durch die Vorlagen 0 und 10 unterstützt. Die Kernelmodule usb_template(4) und cfumass(4) müssen geladen sein. cfumass(4) ist die Schnittstelle zum CTL-Subsystem, das auch für iSCSI- oder Fibre-Channel-Targets benutzt wird. Auf dem Host können Initiatioren von USB-Massenspeichern nur auf eine einzige LUN, LUN 0 zugreifen.

25.4.1. Konfiguration von USB-Massenspeicher Targets mit dem cfumass-Startskript

Der einfachste Weg, ein schreibgeschütztes USBSpeicherziel einzurichten, ist die Verwendung des cfumass rc-Skripts. Kopieren Sie einfach die Dateien, die dem USB-Host präsentiert werden sollen, in das Verzeichnis /var/cfumass und fügen Sie diese Zeile in /etc/rc.conf ein:

cfumass_enable="YES"

Um das Ziel ohne Neustart zu konfigurieren, führen Sie diesen Befehl aus:

# service cfumass start

Im Gegensatz zur seriellen und Netzwerkfunktionalität sollte die Vorlage in /boot/loader.conf nicht auf 0 oder 10 gesetzt werden, da die LUN vor dem Setzen der Vorlage konfiguriert werden muss. Das cfumass rc-Skript setzt beim Start automatisch die richtige Vorlage.

25.4.2. USB-Massenspeicher mit anderen Werkzeugen konfigurieren

Der Rest dieses Kapitels enthält eine detaillierte Beschreibung der Konfiguration ohne die Verwendung des cfumass rc-Skripts. Dies ist beispielsweise notwendig, wenn man eine beschreibbare LUN zur Verfügung stellen will.

Im Gegensatz zu iSCSI ist es bei USB-Massenspeichern nicht zwingend erforderlich, dass der ctld(8) Daemon läuft. Es gibt zwei Möglichkeiten, das Target zu konfigurieren: ctladm(8) oder ctld(8). Beide erfordern, dass das Kernelmodul cfumass.ko geladen ist. Das Modul kann manuell geladen werden:

# kldload cfumass

Wenn cfumass nicht im Kernel integriert ist, kann /boot/loader.conf angepasst werden, damit das Modul beim Booten geladen wird:

cfumass_load="YES"

Eine LUN kann ohne den ctld(8) Daemon erstellt werden:

# ctladm create -b block -o file=/data/target0

Dies stellt den Inhalt des Abbilds von /data/target0 als LUN auf dem USB-Host dar. Die Datei muss vor der Ausführung des Befehls vorhanden sein. Um die LUN beim Systemstart zu konfigurieren, muss das Kommando in /etc/rc.local eingetragen werden.

ctld(8) kann auch benutzt werden, um LUNs zu verwalten. Dazu erstellen Sie eine /etc/ctl.conf und fügen eine Zeile in /etc/rc.conf hinzu, um sicherzustellen, dass ctld(8) beim Booten automatisch gestartet wird. Danach kann der Daemon gestartet werden.

Es folgt ein Beispiel einer einfachen Konfiguration für /etc/ctl.conf. Eine ausführliche Beschreibung der Optionen finden Sie in ctl.conf(5).

target naa.50015178f369f092 {
	lun 0 {
		path /data/target0
		size 4G
	}
}

Dieses Beispiel erstellt ein einzelnes Target mit einer einzigen LUN. naa.50015178f369f092 ist eine Gerätekennung, die aus 32 zufälligen Hexadezimalziffern besteht. path definiert den absoluten Pfad zu einer Datei oder eines zvol, welches die LUN als Speicher nutzen kann. Diese Datei muss vor dem Start von ctld(8) existieren. Die zweite Zeile ist optional und definiert die Größe der LUN.

Damit der ctld(8) Daemon beim Booten gestartet wird, muss diese Zeile in /etc/rc.conf hinzugefügt werden:

ctld_enable="YES"

Sie können ctld(8) mit diesem Befehl direkt starten:

# service ctld start

Der ctld(8) Daemon liest beim Start /etc/ctl.conf. Wenn diese Datei nach dem Start des Daemons bearbeitet wird, müssen die Änderungen neu geladen werden, damit sie sofort wirksam werden:

# service ctld reload

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.