Zbuduj moduł jądra dla NAS-a: sterownik USB-szeregowy CH341

Wiele przejściówek USB-szeregowych z układem CH340 lub CH341 wymaga sterownika jądra ch341. NAS z QTS 6.1 pokazany w tym poradniku nie ma go fabrycznie. Warsztat jądra w Bucket & Code Server IDE buduje moduł dla jądra działającego na NAS-ie, sprawdza jego zgodność i go ładuje.

1. Profilparametry działającego jądra
2. Obszar roboczydrzewo skonfigurowane zgodnie z profilem
3. Budowaniedrivers/usb/serial
4. Sprawdzenievermagic, układ struktury, symbole
5. Ładowanieprzez administratora, na jego ryzyko

Zrzuty ekranu pochodzą z NAS-a z QTS 6.1 i jądrem 6.6.129-qnap. Pola wypełniono zgodnie z opisem w poradniku.

01Co robi warsztat

Publiczne archiwum źródeł GPL firmy QNAP zawiera źródła jądra do QTS 5.2.3, ale nie zawiera jądra działającego na tym NAS-ie z QTS 6.1. Dlatego warsztat odczytuje parametry działającego jądra i konfiguruje zgodnie z nimi drzewo źródeł z kernel.org. Na stronie Jądra widać profil: wersję jądra, kompilator użyty przez QNAP, vermagic i układ struktury struct module w modułach QNAP oraz informację, czy moduły muszą być podpisane.

• Potrzebujesz środowiska Kernel builder z galerii Przykłady (Aplikacje → Przykłady): Ubuntu 24.04 z GCC 13 i narzędziami do budowania jądra. Warsztat wymaga tej samej głównej wersji GCC, której użyto do zbudowania działającego jądra, i sprawdza ją przed przygotowaniem obszaru roboczego.
• Przygotowanie, budowanie i ładowanie wymaga roli administratora; sprawdzenie jest dostępne dla developera. Te same kroki można wykonać poleceniami bvs kernel w terminalu edytora, działającym jako root.

02Przygotuj obszar roboczy

Obszar roboczy to drzewo jądra odpowiadające dokładnie działającej wersji, w folderze kernels/<release> w katalogu danych. Na stronie Jądra naciśnij Przygotuj obszar roboczy:

1. Źródło: pozostaw proponowane. Dla wersji 6.6.129 jest nim drzewo z kernel.org, ponieważ drzewa QNAP zawierają tylko starsze jądra.
2. Środowisko: kernel-builder. W polu Dodatkowe ustawienia wpisz w osobnych wierszach USB_SERIAL=m oraz USB_SERIAL_CH341=m — rdzeń obsługi portu szeregowego USB i sterownik CH341. Pozostaw opcję Zbuduj całe jądro wyłączoną, a następnie naciśnij Przygotuj.
3. Zadanie rozpakowuje źródła, konfiguruje je na podstawie profilu i podanych ustawień, przygotowuje do budowania modułów i sprawdza, czy drzewo buduje się dla dokładnie tej wersji działającego jądra. Karta Obszar roboczy pokazuje stan gotowy. Nieudane przygotowanie zachowuje poprzednie drzewo.

03Projekt

W sekcji Nowy projekt pod Jądro są dwa szablony: własny prosty moduł oraz sterownik ch341. Wybierz Sterownik USB-szeregowy ch341.

Projekt zawiera Makefile, którego cele uruchamiają polecenia warsztatu, oraz workflow dla runnera NAS-a:

# Makefile projektu, uruchamiany jako root w terminalu edytora
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

Przy każdym pushu workflow buduje sterownik z opcją --build-only i go sprawdza. Zbudowany plik ch341.ko trafia do artefaktu przebiegu modules, a nie do obszaru roboczego. Dzięki temu make load nadal ładuje moduł zbudowany przez Ciebie.

04Zbuduj sterownik

Na stronie Jądra przycisk Zbuduj moduły buduje folder projektu albo katalog drzewa jądra. Sterownik ch341 jest częścią drzewa: wybierz Katalog drzewa jądra i wpisz drivers/usb/serial. Polecenie make w projekcie robi to samo.

Budowanie tworzy pliki ch341.ko i usbserial.ko. Obszar roboczy przechowuje ch341.ko w modules/. Nie przechowuje usbserial.ko, ponieważ QNAP dostarcza ten moduł i ładowana jest jego wersja.

05Sprawdź zgodność z działającym jądrem

Sprawdź porównuje moduł z działającym jądrem: vermagic, rozmiar struktury struct module i położenie pól init oraz exit, wymaganie podpisu, moduły zależne i wszystkie potrzebne symbole. Każdy wynik wskazuje, co się nie zgadza i co zrobić.

Jądro QNAP nie podaje listy swoich symboli danych, więc wynik sprawdzenia pokazuje symbole takie jak jiffies jako ostrzeżenia. W wierszu poleceń bvs kernel check ch341 kończy się kodem wyjścia 3, gdy modułu nie wolno ładować.

06Załaduj moduł i poznaj skutki

Moduł działa wewnątrz jądra z pełnymi uprawnieniami jądra. Wadliwy moduł może zatrzymać NAS. Ładuj tylko moduł zbudowany w określonym celu i tylko na NAS-ie, który możesz uruchomić ponownie.

• Załaduj (administrator) lub make load ponownie uruchamia sprawdzenie i ładuje moduł, najpierw jego zależności: tutaj moduł usbserial firmy QNAP. Moduł z błędem wykrytym podczas sprawdzenia nie zostaje załadowany. Wyładuj usuwa go z jądra; moduł będący w użyciu pozostaje załadowany. Każde załadowanie i wyładowanie jest zapisywane w log/kernel-modules.log.
• Moduł załadowany ręcznie znika po ponownym uruchomieniu NAS-a. Aby ładował się przy każdym starcie, dodaj go do modułów jądra aplikacji App Builder. Aktywowanie aplikacji ładuje moduł, a każdy start pakietu ładuje go ponownie.
• Jeśli NAS zatrzymał się bez uporządkowanego zatrzymania pakietu — wskutek awarii, zaniku zasilania lub twardego resetu — podczas uruchomienia, w którym pakiet załadował moduły, przy następnym starcie moduły te są pomijane. Jeden z nich mógł spowodować awarię, a powiadomienie wymienia pominięte moduły. Ręczne załadowanie modułu lub ponowne aktywowanie jego aplikacji pozwala pakietowi załadować go przy kolejnym starcie.
• Po aktualizacji QTS do wersji z innym jądrem przygotuj obszar roboczy dla tego jądra i ponownie zbuduj moduł. Kopia zapasowa nie obejmuje folderu kernels/.