Een kernelmodule voor uw NAS bouwen: de CH341 USB-serieel-driver

Veel USB-serieel-adapters met een CH340- of CH341-chip hebben de kerneldriver ch341 nodig. De hier getoonde NAS met QTS 6.1 bevat die niet. De kernelwerkplaats van Bucket & Code Server IDE bouwt zo'n module voor de actieve kernel van de NAS, controleert de compatibiliteit en laadt hem.

1. Profielkenmerken van de kernel
2. Werkruimteeen passend ingestelde bronboom
3. Bouwendrivers/usb/serial
4. Controlerenvermagic, indeling, symbolen
5. Ladendoor een beheerder, op eigen risico

De afbeeldingen komen van een NAS met QTS 6.1 en kernel 6.6.129-qnap. Elk veld is ingevuld zoals deze handleiding beschrijft.

01Wat de werkplaats doet

Het openbare GPL-archief van QNAP bevat kernelbroncode tot en met QTS 5.2.3, zonder de kernel die op deze NAS met QTS 6.1 draait. De werkplaats leest daarom wat de actieve kernel over zichzelf laat zien en configureert een bronboom van kernel.org die daarbij past. De pagina Kernels toont dit profiel: versie, de compiler die QNAP gebruikte, vermagic en de indeling van struct module in QNAPs eigen modules, en of modules ondertekend moeten zijn.

• U hebt de omgeving Kernel builder uit de Examples-galerij nodig (Apps → Examples): Ubuntu 24.04 met GCC 13 en het gereedschap om de kernel te bouwen. De werkplaats vereist dezelfde GCC-hoofdversie als waarmee de actieve kernel is gebouwd en controleert die voordat de werkruimte wordt voorbereid.
• Voorbereiden, bouwen en laden vereisen de beheerdersrol; controleren vereist de ontwikkelaarsrol. In de terminal van de editor, die als root draait, komen dezelfde stappen overeen met bvs kernel-opdrachten.

02De werkruimte voorbereiden

De werkruimte is een bronboom voor precies de actieve kernel, in kernels/<release> in de gegevensmap. Druk op de pagina Kernels op Prepare the workspace:

1. Source: behoud de voorgestelde bron. Voor 6.6.129 is dat de bronboom van kernel.org, omdat QNAPs eigen bronbomen alleen oudere kernels bevatten.
2. Environment: kernel-builder. Onder Extra settings, één instelling per regel: USB_SERIAL=m en USB_SERIAL_CH341=m, de USB-serieel-kern en de CH341-driver. Laat Build the whole kernel uitgeschakeld en druk op Prepare.
3. Een taak pakt de broncode uit, configureert die volgens het profiel en uw instellingen, bereidt die voor op het bouwen van modules en controleert dat de bronboom precies voor de actieve kernelversie bouwt. De kaart Workspace vermeldt ready. Als de voorbereiding mislukt, blijft de vorige bronboom behouden.

03Het project

New project heeft twee sjablonen onder Kernel: een eigen Hello-module en de ch341-driver. Kies USB serial driver ch341.

Het project bevat een Makefile waarvan de doelen de opdrachten van de werkplaats uitvoeren, en een workflow voor de runner van de NAS:

# Makefile van het project, uitvoeren als root in de terminal van de editor
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

Bij elke push bouwt de workflow de driver met --build-only en controleert hem. Het daarbij gebouwde bestand ch341.ko komt in het artefact modules van de uitvoering, nooit in de map modules/ van de werkruimte. Daardoor blijft make load de module laden die u zelf hebt gebouwd.

04De driver bouwen

Op de pagina Kernels bouwt Build modules een projectmap of een map uit de kernelbronboom. De ch341-driver is onderdeel van die boom: kies A directory of the kernel tree en voer drivers/usb/serial in. make in het project doet hetzelfde.

De bouw maakt ch341.ko en usbserial.ko. De werkruimte bewaart ch341.ko in modules/. Ze bewaart usbserial.ko niet, omdat QNAP die module levert en QNAPs exemplaar wordt geladen.

05Controleren tegen de actieve kernel

Check vergelijkt de module met de actieve kernel: vermagic, de grootte van struct module en de posities van init en exit, of een handtekening verplicht is, de modules waarvan hij afhankelijk is en alle benodigde symbolen. Elke bevinding vermeldt wat afwijkt en wat u kunt doen.

QNAPs kernel vermeldt zijn gegevenssymbolen niet, dus de controle meldt symbolen zoals jiffies als waarschuwingen. Op de opdrachtregel eindigt bvs kernel check ch341 met afsluitstatus 3 als de module niet geladen mag worden.

06Laden en de gevolgen begrijpen

Een module draait binnen de kernel met alle rechten van de kernel. Een defecte module kan de NAS stilleggen. Laad alleen wat u voor een duidelijk doel hebt gebouwd, en alleen op een NAS die u opnieuw kunt starten.

• Load (beheerder), of make load, voert de controle opnieuw uit en laadt de module, eerst de modules waarvan hij afhankelijk is: hier QNAPs usbserial. Een module met een fout bij de controle wordt nooit geladen. Unload verwijdert de module; een module die in gebruik is blijft geladen. Elke laad- en ontlaadactie wordt vastgelegd in log/kernel-modules.log.
• Een handmatig geladen module is na een herstart verdwenen. Vermeld de module bij de kernelmodules van een App Builder-app om hem bij elke start te laden: het activeren van de app laadt hem, en elke start van het pakket laadt hem opnieuw.
• Als de NAS stopte zonder dat het pakket ordelijk werd afgesloten (een crash, stroomuitval of harde reset), tijdens een systeemstart waarin het pakket modules had geladen, slaat de volgende start die modules over. Een ervan kan de crash hebben veroorzaakt; een melding noemt ze. Door een module handmatig te laden of de bijbehorende app opnieuw te activeren, kan de start die module weer laden.
• Bereid na een QTS-update naar een andere kernel de werkruimte van die kernel voor en bouw de module opnieuw. Een back-up bevat kernels/ niet.