Compilare un modulo del kernel per il NAS: il driver USB-seriale CH341

Molti adattatori USB-seriali con chip CH340 o CH341 richiedono il driver ch341 del kernel. Il NAS con QTS 6.1 mostrato qui non lo include. Il laboratorio del kernel di Bucket & Code Server IDE compila questo modulo per il kernel in esecuzione sul NAS, ne verifica la compatibilità e lo carica.

1. Profilocaratteristiche del kernel
2. Spazio di lavoroalbero configurato di conseguenza
3. Compilazionedrivers/usb/serial
4. Verificavermagic, disposizione, simboli
5. Caricamentoda amministratore, a tuo rischio

Le immagini provengono da un NAS con QTS 6.1 e kernel 6.6.129-qnap, con tutti i campi compilati come descritto nella guida.

01Cosa fa il laboratorio

L'archivio GPL pubblico di QNAP contiene i sorgenti del kernel fino a QTS 5.2.3, ma non quelli del kernel di questo NAS con QTS 6.1. Il laboratorio legge quindi le informazioni esposte dal kernel in esecuzione e configura un albero di kernel.org di conseguenza. La pagina Kernels mostra il profilo: versione, compilatore usato da QNAP, vermagic e disposizione di struct module nei moduli QNAP, e l'eventuale obbligo di firma dei moduli.

• Serve l'ambiente Kernel builder della galleria Examples (Apps → Examples): Ubuntu 24.04 con GCC 13 e gli strumenti per compilare il kernel. Il laboratorio richiede la stessa versione principale di GCC del kernel in esecuzione e la controlla prima di preparare lo spazio di lavoro.
• Preparazione, compilazione e caricamento richiedono il ruolo amministratore; la verifica richiede il ruolo sviluppatore. Nel terminale dell'editor, eseguito come root, gli stessi passaggi corrispondono ai comandi bvs kernel.

02Preparare lo spazio di lavoro

Lo spazio di lavoro è un albero del kernel corrispondente esattamente al kernel in esecuzione, in kernels/<release> nella cartella dei dati. Nella pagina Kernels premi Prepare the workspace:

1. Source: lascia la sorgente proposta. Per 6.6.129 è l'albero di kernel.org, perché quelli di QNAP contengono solo kernel precedenti.
2. Environment: kernel-builder. In Extra settings, una voce per riga: USB_SERIAL=m e USB_SERIAL_CH341=m, il nucleo USB-seriale e il driver CH341. Lascia disattivato Build the whole kernel, poi premi Prepare.
3. Un processo estrae i sorgenti, li configura secondo il profilo e le tue impostazioni, li prepara per compilare moduli e verifica che l'albero compili esattamente per la versione in esecuzione. La scheda Workspace indica ready. Se la preparazione fallisce, l'albero precedente viene conservato.

03Il progetto

New project offre due modelli sotto Kernel: un semplice modulo dimostrativo da personalizzare e il driver ch341. Scegli USB serial driver ch341.

Il progetto contiene un Makefile i cui target eseguono i comandi del laboratorio e un workflow per il runner del NAS:

# Makefile del progetto, da eseguire come root nel terminale dell'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

A ogni push, il workflow compila il driver con --build-only e lo verifica. Il file ch341.ko ottenuto finisce nell'artefatto modules dell'esecuzione, mai nella cartella modules/ dello spazio di lavoro: make load continua quindi a caricare il modulo compilato da te.

04Compilare il driver

Nella pagina Kernels, Build modules compila una cartella di progetto o una directory dell'albero del kernel. Il driver ch341 fa parte dell'albero: scegli A directory of the kernel tree e inserisci drivers/usb/serial. make nel progetto fa la stessa cosa.

La compilazione produce ch341.ko e usbserial.ko. Lo spazio di lavoro conserva ch341.ko in modules/. Non conserva usbserial.ko, perché QNAP fornisce già quel modulo ed è la sua copia a essere caricata.

05Verificare la compatibilità con il kernel in esecuzione

Check confronta il modulo con il kernel in esecuzione: vermagic, dimensione di struct module e posizioni di init ed exit, obbligo di firma, moduli da cui dipende e tutti i simboli necessari. Ogni risultato indica la differenza e cosa fare.

Il kernel QNAP non elenca i propri simboli di dati, quindi la verifica segnala come avvisi simboli quali jiffies. Da riga di comando, bvs kernel check ch341 termina con codice di uscita 3 quando il modulo non deve essere caricato.

06Caricare il modulo e comprenderne gli effetti

Un modulo viene eseguito nel kernel con tutti i suoi privilegi. Un modulo difettoso può bloccare il NAS. Carica solo ciò che hai compilato per uno scopo preciso, e solo su un NAS che puoi riavviare.

• Load (amministratore), o make load, ripete la verifica e carica il modulo, prima le dipendenze: qui usbserial di QNAP. Un modulo con un errore nella verifica non viene mai caricato. Unload lo rimuove; un modulo in uso resta caricato. Ogni caricamento e scaricamento viene registrato in log/kernel-modules.log.
• Un modulo caricato a mano scompare dopo un riavvio. Per caricarlo a ogni avvio, indicane il nome nei moduli del kernel di un'app App Builder: l'attivazione dell'app lo carica e ogni avvio del pacchetto lo ricarica.
• Se il NAS si è fermato senza l'arresto ordinato del pacchetto (blocco, interruzione di corrente, reset forzato), durante una sessione in cui il pacchetto aveva caricato moduli, all'avvio successivo quei moduli vengono esclusi, perché uno di essi potrebbe aver causato il blocco. Una notifica li elenca. Caricarne uno a mano o riattivare la sua app ne consente di nuovo il caricamento all'avvio.
• Dopo un aggiornamento QTS a un altro kernel, prepara lo spazio di lavoro di quel kernel e ricompila il modulo. I backup non includono kernels/.