# Kernel modules for the NAS's own kernel

A module loads only into the kernel it was built for. QNAP ships no kernel headers and, on the units measured, no
`/proc/config.gz`, and its published GPL source stops at QTS 5.2.3 (kernel 5.10.60). Bucket & Code Server IDE's
kernel workshop builds modules for the running kernel anyway and checks each one before it may load.

## What must match

- **The vermagic**, for example `6.6.129-qnap SMP preempt mod_unload `: the release, `SMP`, the preemption model,
  `mod_unload`, and `modversions` when the kernel has it.
- **The layout of `struct module`** in the module's `.gnu.linkonce.this_module` section. Its size and field offsets
  change with options such as tracing, jump labels or BTF.
- **The symbols** the module needs, which the kernel must export. The compiler adds some itself: with return
  thunks on, a module needs `__x86_return_thunk`, which a QNAP kernel may keep local, and the load then fails
  with "Unknown symbol". So a compiler option alone (`RETHUNK`, `RETPOLINE`, function tracing) can make a module
  unloadable.

## Without Bucket & Code Server IDE

What must match holds for a module built anywhere. The steps below are Bucket & Code Server IDE's: the package reads
the running kernel's profile, prepares a tree that matches it, and checks each module before it loads. This skill
has no tested way to do those steps by hand on your own computer.

## The steps in Bucket & Code Server IDE

```sh
bvs kernel profile        # the running kernel: compiler, vermagic, struct module, the settings a tree gets
bvs kernel sources        # the kernel sources in the catalog, and which fits this NAS
bvs kernel prepare        # a workspace for the running kernel (a job, admin); --option NAME=VALUE adds a setting
bvs kernel make --project hello-kmod     # builds projects/hello-kmod with M=, into the workspace's modules/
bvs kernel check hello                   # the compatibility check; exit 3 when it must not load
bvs kernel load hello                    # check, then load (root); bvs kernel unload hello
```

- **Prepare** needs an environment with `gcc` and `make` whose GCC major version is the kernel's; `bvs kernel
  profile` names the kernel's compiler. The `kernel-builder` preset (Ubuntu 24.04, GCC 13) matched the one 6.6
  kernel measured, 6.6.129, which QNAP built with GCC 13.2. It configures QNAP's tree with the
  model's configuration when QNAP's release has the running version, otherwise kernel.org's tree with the settings
  read from the running kernel (preemption, `MODVERSIONS`, return thunks, IBT, ORC, BTF and more), runs
  `modules_prepare`, and insists that `make kernelrelease` prints `uname -r`.
- **Make** builds an out-of-tree project (`--project <folder of projects/>`), an in-tree directory QNAP does not
  ship (`--dir drivers/usb/serial`), or the whole kernel. A module whose name QNAP already ships in
  `/lib/modules/<release>` is not copied: QNAP's copy stays the one that loads.
- **Check** compares machine, vermagic, the `struct module` layout, a required signature, dependencies and every
  symbol with the running kernel. A compiler-inserted symbol the kernel lacks, a symbol it keeps local, or a
  function it does not have is an error, and the module never loads. QNAP's kernels list no data symbols in
  `/proc/kallsyms`, so those are warnings ("cannot be looked up"); the kernel itself refuses a module whose symbol
  is really missing, with "Unknown symbol".
- **Load** is bvsd's own `finit_module` on the checked file (same sha256), dependencies first. Use it instead of
  `insmod`.
- **A load by hand lasts until the next reboot.** At its start the package loads only the modules of active App
  Builder apps. So a module the NAS needs at every boot belongs in an app: activation loads it after the check,
  and the package loads it again at every start. When a boot with loaded modules ends without the package's
  ordered stop (a crash, a power cut), those modules are held at the next start and load again only when you load
  them by hand or activate their app again.
- A CI build uses `bvs kernel make --build-only`: it leaves the `.ko` where make wrote it and keeps it as the run's
  artifact, so a push never replaces the module you built and tested from the editor.

## A kernel driver QNAP does not ship: ch341

A driver from the kernel's own tree needs its setting and the setting of the core it depends on. For the CH340 and
CH341 USB-serial driver, `usbserial` is the core (QNAP ships it) and `ch341` the driver:

```sh
bvs kernel prepare --option USB_SERIAL=m --option USB_SERIAL_CH341=m
bvs kernel make --dir drivers/usb/serial
bvs kernel check ch341 && bvs kernel load ch341
```

Without `USB_SERIAL_CH341=m` the driver stays switched off in the tree and the make builds no `ch341.ko`. New
project's ch341 template (`kernel-ch341`) and the Examples gallery's "USB serial driver ch341" hold these steps as
a Makefile (`make prepare`, `make`, `make check`, `make load`).

## Limits

- aarch64 is handled by the reader, the profile and the check, but no module has been built for a real ARM QNAP.
- A module built for one firmware's kernel does not load after a firmware update that changes the kernel: prepare
  and make again.
- The `ch341.ko` the workshop builds passes the check against QNAP's 6.6.129 kernel, but no test has loaded it or
  talked to an adapter through it yet.

## Sources

Bucket & Code Server IDE's user guide (`bvs guide`, "Kernel workshop") and its `bvs kernel` command; the kernel
versions of the firmware from QNAP Club Poland's [guidelines.md](https://forum.qnap.net.pl/llms/guidelines.md).
