Unofficial
Sur cette page
  1. 01Ce que fait l'atelier
  2. 02Préparer l'espace de travail
  3. 03Le projet
  4. 04Compiler le pilote
  5. 05Vérifier la compatibilité avec le noyau actif
  6. 06Charger le module et comprendre les conséquences

Compiler un module du noyau pour votre NAS : le pilote USB-série CH341

De nombreux adaptateurs USB-série équipés d'une puce CH340 ou CH341 nécessitent le pilote ch341 du noyau. Le NAS sous QTS 6.1 présenté ici n'en dispose pas. L'atelier du noyau de Bucket & Code Server IDE compile ce module pour le noyau actif du NAS, vérifie sa compatibilité et le charge.

  1. Profilles caractéristiques du noyau
  2. Espace de travailune arborescence configurée en conséquence
  3. Compilationdrivers/usb/serial
  4. Vérificationvermagic, disposition, symboles
  5. Chargementpar un administrateur, à vos risques

Les captures proviennent d'un NAS sous QTS 6.1 avec le noyau 6.6.129-qnap. Chaque champ est rempli comme indiqué dans ce guide.

01Ce que fait l'atelier

L'archive GPL publique de QNAP propose les sources du noyau jusqu'à QTS 5.2.3, sans celles du noyau actif sur ce NAS sous QTS 6.1. L'atelier lit donc les informations exposées par le noyau actif et configure une arborescence de kernel.org en conséquence. La page Kernels affiche ce profil : version, compilateur utilisé par QNAP, vermagic et disposition de struct module dans les modules de QNAP, ainsi que l'obligation éventuelle de signer les modules.

Noyau actif : version 6.6.129-qnap, x86_64 TS-X74P, compilateur x86_64-QNAP_gcc13-linux-gnu-gcc 13.2.0, binutils 2.41, vermagic 6.6.129-qnap SMP preempt mod_unload, struct module de 1152 octets avec init à 312 et exit à 1064 ; les modules QNAP ne sont pas signés ; informations lues dans les modules de QNAP
  • Il vous faut l'environnement Kernel builder de la galerie Examples (Apps → Examples) : Ubuntu 24.04 avec GCC 13 et les outils de compilation du noyau. L'atelier exige la même version majeure de GCC que celle utilisée pour le noyau actif et la vérifie avant de préparer l'espace de travail.
  • La préparation, la compilation et le chargement nécessitent le rôle administrateur ; la vérification nécessite le rôle développeur. Dans le terminal de l'éditeur, qui s'exécute en root, les mêmes étapes correspondent aux commandes bvs kernel.

02Préparer l'espace de travail

L'espace de travail est une arborescence du noyau correspondant exactement au noyau actif, dans kernels/<release> du dossier de données. Sur la page Kernels, cliquez sur Prepare the workspace :

  1. Source : conservez la proposition. Pour 6.6.129, il s'agit de l'arborescence de kernel.org, car celles de QNAP ne contiennent que des noyaux plus anciens. Sources du noyau : Linux 6.6.129 de kernel.org, proposé, contient ce noyau, téléchargement de 134 MB ; sources GPL QNAP de QTS 5.2.3 avec les noyaux 5.10.60, 4.14.24 et 4.2.8, autre version, 780 MB
  2. Environment : kernel-builder. Dans Extra settings, saisissez une option par ligne : USB_SERIAL=m et USB_SERIAL_CH341=m, le cœur USB-série et le pilote CH341. Laissez Build the whole kernel désactivé, puis cliquez sur Prepare. Préparation de l'espace de travail de 6.6.129-qnap : Source proposée, Environment kernel-builder, Extra settings USB_SERIAL=m et USB_SERIAL_CH341=m, Build the whole kernel décoché et bouton Prepare
  3. Une tâche décompresse les sources, les configure à partir du profil et de vos options, les prépare pour la compilation de modules et vérifie que l'arborescence cible exactement la version active. La carte Workspace indique ready. Si la préparation échoue, l'arborescence précédente est conservée. Workspace, état ready : source linux-6.6.129 de kernel.org, configuration defconfig+profile avec USB_SERIAL=m et USB_SERIAL_CH341=m, environnement kernel-builder et boutons Build modules et Delete

03Le projet

New project propose deux modèles sous Kernel : un module de démonstration à personnaliser et le pilote ch341. Choisissez USB serial driver ch341.

Modèles Kernel de New project : Kernel module, module de démonstration avec Kbuild et Makefile ; USB serial driver ch341, pilote du noyau pour adaptateurs USB-série CH340 et CH341, sélectionné

Le projet contient un Makefile dont les cibles exécutent les commandes de l'atelier, ainsi qu'un workflow pour le runner du NAS :

# Makefile du projet, à exécuter en root dans le terminal de l'éditeur
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

À chaque push, le workflow compile le pilote avec --build-only et le vérifie. Le fichier ch341.ko de cette compilation rejoint l'artefact modules de l'exécution, jamais le dossier modules/ de l'espace de travail : make load continue donc de charger le module que vous avez compilé.

04Compiler le pilote

Sur la page Kernels, Build modules compile un dossier de projet ou un répertoire de l'arborescence du noyau. Le pilote ch341 fait partie de cette arborescence : choisissez A directory of the kernel tree et saisissez drivers/usb/serial. La commande make dans le projet fait la même chose.

Build modules dans 6.6.129-qnap : What to build réglé sur A directory of the kernel tree ; Directory drivers/usb/serial ; Targets vide ; bouton Build

La compilation produit ch341.ko et usbserial.ko. L'espace de travail conserve ch341.ko dans modules/. Il ne conserve pas usbserial.ko, car QNAP fournit déjà ce module et c'est sa copie qui est chargée.

Modules de l'espace de travail : bvs_hello et ch341, tous deux non chargés, avec leur taille, leur date de compilation et les boutons Check et Load

05Vérifier la compatibilité avec le noyau actif

Check compare le module au noyau actif : vermagic, taille de struct module et positions d'init et d'exit, obligation de signature, modules dont il dépend et tous les symboles nécessaires. Chaque résultat indique les différences et la marche à suivre.

Vérification de ch341 : chargeable ; avertissement indiquant que 2 symboles, jiffies et kmalloc_caches, ne peuvent pas être recherchés car ce noyau ne répertorie aucun symbole de données, et que le noyau refuse le module au chargement si l'un d'eux manque

Le noyau QNAP ne répertorie pas ses symboles de données ; la vérification signale donc les symboles tels que jiffies comme avertissements. En ligne de commande, bvs kernel check ch341 se termine avec le code de sortie 3 lorsque le module ne doit pas être chargé.

06Charger le module et comprendre les conséquences

Un module s'exécute dans le noyau avec tous ses droits. Un module défectueux peut arrêter le NAS. Ne chargez que ce que vous avez compilé dans un but précis, sur un NAS que vous pouvez redémarrer.

  • Load (administrateur), ou make load, relance la vérification et charge le module après ses dépendances : ici le module usbserial de QNAP. Un module présentant une erreur lors de la vérification n'est jamais chargé. Unload le retire ; un module en cours d'utilisation reste chargé. Chaque chargement et déchargement est consigné dans log/kernel-modules.log.
  • Un module chargé manuellement disparaît après un redémarrage. Pour le charger à chaque démarrage, ajoutez son nom aux modules du noyau d'une application App Builder : l'activation de l'application le charge, puis chaque démarrage du paquet le recharge.
  • Si le NAS s'est arrêté sans arrêt ordonné du paquet (plantage, coupure de courant, réinitialisation matérielle), lors d'un démarrage où le paquet avait chargé des modules, le démarrage suivant les ignore, car l'un d'eux peut avoir causé le plantage. Une notification les nomme. Charger un module manuellement ou réactiver son application autorise à nouveau son chargement au démarrage.
  • Après une mise à jour de QTS vers un autre noyau, préparez l'espace de travail de ce noyau et recompilez le module. Une sauvegarde n'inclut pas kernels/.