Unofficial
本頁內容
  1. 01工作坊的功能
  2. 02準備工作區
  3. 03專案
  4. 04建置驅動程式
  5. 05檢查與執行中核心的相容性
  6. 06載入模組及其影響

為 NAS 建置核心模組：CH341 USB 序列埠驅動程式

許多採用 CH340 或 CH341 晶片的 USB 序列埠轉接器需要核心的 ch341 驅動程式。這裡示範的 QTS 6.1 NAS 未附此驅動程式。Bucket & Code Server IDE 的核心工作坊會為 NAS 執行中的核心建置這類模組、檢查與該核心的相容性，再載入模組。

  1. 設定檔核心的資訊
  2. 工作區依資訊設定的原始碼樹
  3. 建置drivers/usb/serial
  4. 檢查vermagic、配置、符號
  5. 載入由管理員操作，風險自負

圖片來自執行 QTS 6.1 與核心 6.6.129-qnap 的 NAS，每個欄位均依本指南的說明填寫。

01工作坊的功能

QNAP 公開的 GPL 檔案庫所列的核心原始碼只到 QTS 5.2.3，並未包含這台 QTS 6.1 NAS 執行中的核心。因此，工作坊會讀取執行中核心所提供的自身資訊，並據此設定來自 kernel.org 的核心原始碼樹。Kernels 頁面會顯示此設定檔：版本、QNAP 使用的編譯器、QNAP 自有模組中的 vermagic 與 struct module 配置，以及模組是否必須簽署。

執行中的核心：版本 6.6.129-qnap，x86_64 TS-X74P，編譯器 x86_64-QNAP_gcc13-linux-gnu-gcc 13.2.0，binutils 2.41，vermagic 6.6.129-qnap SMP preempt mod_unload，struct module 為 1152 位元組，init 位於 312、exit 位於 1064；QNAP 模組沒有簽章；資訊讀取自 QNAP 自有模組
  • 您需要 Examples 範例庫（Apps → Examples）中的 Kernel builder 環境：Ubuntu 24.04，搭配 GCC 13 與核心建置工具。工作坊要求 GCC 的主要版本與建置執行中核心所用的版本相同，並會在準備工作區之前檢查。
  • 準備、建置與載入需要管理員角色；檢查需要開發者角色。在以 root 執行的編輯器終端機中，也可以用 bvs kernel 命令執行相同步驟。

02準備工作區

工作區是與執行中核心完全對應的核心原始碼樹，位於資料資料夾的 kernels/<release>。在 Kernels 頁面按下 Prepare the workspace：

  1. Source：保留建議的來源。對 6.6.129 而言，這是 kernel.org 的原始碼樹，因為 QNAP 自有的原始碼樹只包含較舊的核心。 核心來源：kernel.org 的 Linux 6.6.129，建議使用，包含此核心，下載 134 MB；QNAP 的 QTS 5.2.3 GPL 原始碼包含核心 5.10.60、4.14.24 與 4.2.8，屬於其他版本，780 MB
  2. Environment：kernel-builder。在 Extra settings 中每行輸入一項：USB_SERIAL=m 與 USB_SERIAL_CH341=m，分別是 USB 序列埠核心支援與 CH341 驅動程式。保持 Build the whole kernel 關閉，再按下 Prepare。 準備 6.6.129-qnap 的工作區：Source 採用建議值，Environment 為 kernel-builder，Extra settings 為 USB_SERIAL=m 與 USB_SERIAL_CH341=m，Build the whole kernel 未勾選，以及 Prepare 按鈕
  3. 工作會解壓縮原始碼、依設定檔與您的選項設定、準備模組建置，並確認原始碼樹的建置目標與執行中的版本完全一致。Workspace 卡片會顯示 ready。若準備失敗，會保留先前的原始碼樹。 Workspace，狀態 ready：來源為 kernel.org 的 linux-6.6.129，設定為 defconfig+profile 加上 USB_SERIAL=m 與 USB_SERIAL_CH341=m，環境為 kernel-builder，以及 Build modules 與 Delete 按鈕

03專案

New project 的 Kernel 下有兩個範本：您自己的簡單 Hello 模組，以及 ch341 驅動程式。請選擇 USB serial driver ch341。

New project 的 Kernel 範本：Kernel module 是含 Kbuild 與 Makefile 的簡單 Hello 核心模組；已選取的 USB serial driver ch341 是核心原始碼提供、供 CH340 與 CH341 USB 序列埠轉接器使用的 ch341 驅動程式

專案包含 Makefile，其目標會執行工作坊的命令，另有供 NAS 執行器使用的工作流程：

# 專案的 Makefile，在編輯器終端機中以 root 執行
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

每次推送時，工作流程會以 --build-only 建置驅動程式並檢查。該次建置的 ch341.ko 會放入執行結果的 modules 成品，絕不放進工作區的 modules/ 資料夾，因此 make load 載入的仍是您自行建置的模組。

04建置驅動程式

在 Kernels 頁面，Build modules 會建置專案資料夾或核心原始碼樹中的目錄。ch341 驅動程式屬於原始碼樹的一部分：請選擇 A directory of the kernel tree，並輸入 drivers/usb/serial。在專案中執行 make 也會進行相同操作。

6.6.129-qnap 的 Build modules：What to build 選擇 A directory of the kernel tree；Directory 為 drivers/usb/serial；Targets 留空；以及 Build 按鈕

建置會產生 ch341.ko 與 usbserial.ko。工作區會將 ch341.ko 保存在 modules/ 中。由於 QNAP 已提供 usbserial.ko，而且會載入 QNAP 的版本，因此不會保留這個檔案。

工作區的模組：bvs_hello 與 ch341，兩者皆未載入，顯示大小、建置日期，以及 Check 與 Load 按鈕

05檢查與執行中核心的相容性

Check 會比較模組與執行中的核心：vermagic、struct module 大小與 init 和 exit 的位置、是否需要簽章、相依模組，以及所有需要的符號。每項結果都會說明不符之處與處理方式。

ch341 檢查結果：可載入；警告指出，因為此核心未列出資料符號，無法查核 2 個符號 jiffies 與 kmalloc_caches，若缺少其中任一符號，核心會在載入時拒絕模組

QNAP 的核心未列出自身的資料符號，因此檢查會將 jiffies 等符號列為警告。在命令列中，當模組不得載入時，bvs kernel check ch341 會以結束狀態 3 結束。

06載入模組及其影響

模組在核心內部執行，擁有核心的全部權限。有缺陷的模組可能讓 NAS 停止運作。請只載入您為明確目的而建置的模組，並且只在您可以重新啟動的 NAS 上操作。

  • Load（管理員）或 make load 會再次檢查，再載入模組，並先載入相依模組：此處為 QNAP 的 usbserial。檢查發現錯誤的模組絕不會載入。Unload 會移除模組；使用中的模組則會維持載入。每次載入與卸載都會寫入 log/kernel-modules.log。
  • 手動載入的模組會在重新啟動後消失。若要在每次啟動時載入，請將其名稱加入 App Builder 應用程式的核心模組清單：啟用應用程式時會載入模組，而套件每次啟動時也會重新載入。
  • 如果在套件曾載入模組的那次開機期間，NAS 未經套件正常停止便中止運作（當機、斷電、強制重設），下次啟動時會略過這些模組，因為其中一個可能是當機原因，通知會列出模組名稱。手動載入某個模組，或再次啟用其應用程式後，啟動時便可再次載入該模組。
  • QTS 更新為其他核心後，請準備該核心的工作區並重新建置模組。備份不包含 kernels/。