Unofficial
Auf dieser Seite
  1. 01Was die Werkstatt macht
  2. 02Arbeitsbereich vorbereiten
  3. 03Das Projekt
  4. 04Treiber bauen
  5. 05Mit dem laufenden Kernel abgleichen
  6. 06Laden und die Folgen verstehen

Ein Kernelmodul für Ihr NAS bauen: der CH341-USB-Seriell-Treiber

Viele USB-Seriell-Adapter mit einem CH340- oder CH341-Chip benötigen den Kerneltreiber ch341. Auf dem hier gezeigten NAS mit QTS 6.1 fehlt er. Die Kernelwerkstatt von Bucket & Code Server IDE baut ein solches Modul für den laufenden Kernel des NAS, prüft es gegen diesen Kernel und lädt es.

  1. ProfilEigenschaften des Kernels
  2. Arbeitsbereichpassend konfigurierter Quellbaum
  3. Bauendrivers/usb/serial
  4. Prüfenvermagic, Layout, Symbole
  5. Ladendurch Admins, auf eigenes Risiko

Die Bilder stammen von einem NAS mit QTS 6.1 und Kernel 6.6.129-qnap. Alle Felder sind wie in dieser Anleitung beschrieben ausgefüllt.

01Was die Werkstatt macht

QNAPs öffentliches GPL-Archiv enthält Kernelquellen bis QTS 5.2.3, aber keine für den Kernel dieses NAS mit QTS 6.1. Die Werkstatt liest daher die Angaben des laufenden Kernels und konfiguriert einen Quellbaum von kernel.org entsprechend. Die Seite Kernels zeigt dieses Profil: Version, den von QNAP verwendeten Compiler, vermagic und das Layout von struct module in QNAPs Modulen sowie eine mögliche Signaturpflicht.

Laufender Kernel: Version 6.6.129-qnap, x86_64 TS-X74P, Compiler x86_64-QNAP_gcc13-linux-gnu-gcc 13.2.0, binutils 2.41, vermagic 6.6.129-qnap SMP preempt mod_unload, struct module mit 1152 Bytes, init an Position 312 und exit an 1064; QNAPs Module sind nicht signiert; aus QNAPs eigenen Modulen ausgelesen
  • Sie benötigen die Umgebung Kernel builder aus der Examples-Galerie (Apps → Examples): Ubuntu 24.04 mit GCC 13 und den Werkzeugen zum Kernelbau. Die Werkstatt verlangt dieselbe GCC-Hauptversion wie der laufende Kernel und prüft sie vor dem Vorbereiten des Arbeitsbereichs.
  • Vorbereiten, Bauen und Laden erfordern die Adminrolle; Prüfen erfordert die Entwicklerrolle. Im Terminal des Editors, das als root läuft, entsprechen diese Schritte den Befehlen bvs kernel.

02Arbeitsbereich vorbereiten

Der Arbeitsbereich ist ein Quellbaum für genau den laufenden Kernel unter kernels/<release> im Datenordner. Klicken Sie auf der Seite Kernels auf Prepare the workspace:

  1. Source: Belassen Sie die vorgeschlagene Quelle. Für 6.6.129 ist dies der Quellbaum von kernel.org, da QNAPs eigene Quellbäume nur ältere Kernel enthalten. Kernelquellen: Linux 6.6.129 von kernel.org, vorgeschlagen, enthält diesen Kernel, 134 MB heruntergeladen; QNAPs GPL-Quellen für QTS 5.2.3 mit den Kerneln 5.10.60, 4.14.24 und 4.2.8, andere Version, 780 MB
  2. Environment: kernel-builder. Unter Extra settings je eine Einstellung pro Zeile: USB_SERIAL=m und USB_SERIAL_CH341=m, der USB-Seriell-Kern und der CH341-Treiber. Lassen Sie Build the whole kernel ausgeschaltet und klicken Sie auf Prepare. Arbeitsbereich für 6.6.129-qnap vorbereiten: Source vorgeschlagen, Environment kernel-builder, Extra settings USB_SERIAL=m und USB_SERIAL_CH341=m, Build the whole kernel nicht angekreuzt, Schaltfläche Prepare
  3. Ein Auftrag entpackt die Quellen, konfiguriert sie anhand des Profils und Ihrer Einstellungen, bereitet sie für den Modulbau vor und prüft, ob der Quellbaum genau die laufende Kernelversion erzeugt. Die Karte Workspace zeigt ready. Schlägt das Vorbereiten fehl, bleibt der bisherige Quellbaum erhalten. Workspace, Status ready: Quelle linux-6.6.129 von kernel.org, Konfiguration defconfig+profile mit USB_SERIAL=m und USB_SERIAL_CH341=m, Umgebung kernel-builder und Schaltflächen Build modules und Delete

03Das Projekt

New project bietet unter Kernel zwei Vorlagen: ein eigenes Hello-Modul und den ch341-Treiber. Wählen Sie USB serial driver ch341.

Kernel-Vorlagen unter New project: Kernel module, ein Hello-Kernelmodul mit Kbuild und Makefile; USB serial driver ch341, der kernelseitige ch341-Treiber für CH340- und CH341-USB-Seriell-Adapter, ausgewählt

Das Projekt enthält ein Makefile, dessen Ziele die Befehle der Werkstatt ausführen, und einen Workflow für den Runner des NAS:

# Makefile des Projekts, als root im Terminal des Editors ausführen
make prepare   # bvs kernel prepare --option USB_SERIAL=m --option USB_SERIAL_CH341=m
make           # bvs kernel make --dir drivers/usb/serial
make check     # bvs kernel check ch341
make load      # bvs kernel load ch341
make unload    # bvs kernel unload ch341

Bei jedem Push baut der Workflow den Treiber mit --build-only und prüft ihn. Die dabei erzeugte Datei ch341.ko landet im Artefakt modules des Laufs, niemals im Ordner modules/ des Arbeitsbereichs. Dadurch lädt make load weiterhin das von Ihnen gebaute Modul.

04Treiber bauen

Auf der Seite Kernels baut Build modules einen Projektordner oder ein Verzeichnis des Kernelquellbaums. Der ch341-Treiber ist Teil dieses Baums: Wählen Sie A directory of the kernel tree und geben Sie drivers/usb/serial ein. make im Projekt führt denselben Schritt aus.

Build modules in 6.6.129-qnap: What to build auf A directory of the kernel tree gesetzt; Directory drivers/usb/serial; Targets leer; Schaltfläche Build

Der Bau erzeugt ch341.ko und usbserial.ko. Der Arbeitsbereich bewahrt ch341.ko in modules/ auf. usbserial.ko wird nicht übernommen, da QNAP dieses Modul liefert und QNAPs Kopie geladen wird.

Module des Arbeitsbereichs: bvs_hello und ch341, beide nicht geladen, mit Größe, Baudatum sowie den Schaltflächen Check und Load

05Mit dem laufenden Kernel abgleichen

Check vergleicht das Modul mit dem laufenden Kernel: vermagic, die Größe von struct module und die Positionen von init und exit, eine erforderliche Signatur, die Module, von denen es abhängt, und alle benötigten Symbole. Jeder Befund nennt die Abweichung und die nötigen Schritte.

Prüfung von ch341: ladbar; Warnung, dass 2 Symbole, jiffies und kmalloc_caches, nicht nachgeschlagen werden können, weil dieser Kernel keine Datensymbole auflistet, und dass der Kernel das Modul beim Laden ablehnt, falls eines davon fehlt

QNAPs Kernel listet seine Datensymbole nicht auf. Die Prüfung meldet daher Symbole wie jiffies als Warnungen. Auf der Befehlszeile endet bvs kernel check ch341 mit Exitstatus 3, wenn das Modul nicht geladen werden darf.

06Laden und die Folgen verstehen

Ein Modul läuft innerhalb des Kernels mit all dessen Rechten. Ein fehlerhaftes Modul kann das NAS zum Stillstand bringen. Laden Sie nur Module, die Sie für einen bestimmten Zweck gebaut haben, und nur auf einem NAS, das Sie neu starten können.

  • Load (Admin) oder make load prüft erneut und lädt das Modul, seine Abhängigkeiten zuerst: hier QNAPs usbserial. Ein Modul mit einem Prüffehler wird niemals geladen. Unload entfernt es; ein verwendetes Modul bleibt geladen. Jedes Laden und Entladen wird in log/kernel-modules.log protokolliert.
  • Ein von Hand geladenes Modul ist nach einem Neustart weg. Damit es bei jedem Start geladen wird, tragen Sie es unter den Kernelmodulen einer App-Builder-App ein: Das Aktivieren der App lädt es, und jeder Start des Pakets lädt es erneut.
  • Wurde das NAS ohne geordnetes Beenden des Pakets angehalten (Absturz, Stromausfall, harter Reset), nachdem das Paket in diesem Systemlauf Module geladen hatte, lässt der nächste Start diese Module aus. Eines davon könnte den Absturz verursacht haben; eine Meldung nennt sie. Wenn Sie ein Modul von Hand laden oder seine App erneut aktivieren, darf es beim Start wieder geladen werden.
  • Nach einem QTS-Update auf einen anderen Kernel bereiten Sie dessen Arbeitsbereich vor und bauen das Modul erneut. Eine Sicherung enthält kernels/ nicht.