Integrate out-of-tree DKMS modules into the kernel at build time

[Bjordis Collaku (bjordiscollaku)]

Summary

This adds a build-time mechanism that compiles out-of-tree kernel modules from
their DKMS source packages and bundles them into the kernel package, in the same
run that builds the kernel. The device receives one self-contained kernel
package: the module is present and pinned to the exact kernel it was built
against, with no DKMS, compiler, or headers required on the target.

The mechanism is module-agnostic. It is implemented as a standalone, documented
tool (debian/scripts/bundle-dkms-modules.sh) that debian/rules invokes during
the build, and it is driven by a manifest, so onboarding any out-of-tree module
is a two-line change with no change to the build logic.

Design history and rationale: #44.

How it works, in order

flowchart TD
    P["module DKMS source package<br/>(from the distro apt source)"]
    K["1. Build kernel + headers<br/>in one packaging run"]
    H["2. Stage headers in the build tree"]
    R["3. debian/rules calls<br/>bundle-dkms-modules.sh"]
    RES["4. Resolve source + tokens<br/>via dpkg -L and dkms.conf"]
    D["5. dkms build against the<br/>staged headers (private tree)"]
    J{"6. Built a .ko?"}
    X["Fail the build<br/>with precise diagnostics"]
    S["7. Extract debug to -dbg,<br/>strip the shipped copy"]
    B["8. Bundle into the kernel image<br/>under lib/modules/KVER/extra"]
    O["9. On device: depmod indexes it,<br/>modprobe + autoload work"]

    P -. "Build-Depends" .-> RES
    K --> H --> R --> RES --> D --> J
    J -- "no" --> X
    J -- "yes" --> S --> B --> O

Loading

1. The module's *-dkms package is installed via Build-Depends (build-time
   only; it never enters any binary package's runtime dependencies).
2. The kernel and its headers are built and staged in the same run.
3. debian/rules (override_dh_auto_install) invokes the bundling tool once the
   trees are staged.
4. For each manifest module the tool resolves the source directory and the dkms
   name/version tokens from dpkg -L and the shipped dkms.conf.
5. It runs dkms build against the staged headers in a private DKMS tree, so the
   module matches the exact kernel and the build stays rootless under fakeroot.
6. It judges success by the produced artifact, not by exit codes, and fails the
   build with precise diagnostics if a listed module produces nothing.
7. It extracts the module's debug into the -dbg package and strips the shipped
   copy, the same two-stage handling an in-tree module gets.
8. It installs the module into the kernel image under lib/modules/<KVER>/extra/,
   guarding against duplicate and in-tree name collisions.
9. On the device, the standard postinst depmod indexes extra/, so modprobe
   and autoload resolve the module.

The tool: debian/scripts/bundle-dkms-modules.sh

The bundling logic is a single standalone tool with a documented CLI, so
debian/rules stays a thin call, future changes (a new guard, signing,
compression) touch one file, and a developer can re-run just the bundling step
against already-staged trees.

Required:
  --kver KVER               kernel release (uname -r)
  --headers-dir DIR         absolute path to the staged kernel headers root
  --image-pkg-dir DIR       linux-image staging tree root
  --dbg-pkg-dir DIR         linux-image-dbg staging tree root
Optional:
  --modules-manifest FILE   default: debian/dkms-modules
  --arch ARCH               default: aarch64 (uname -m vocabulary for dkms)
  --objcopy PATH            default: aarch64-linux-gnu-objcopy, then objcopy
  -h, --help                full usage, prerequisites, and examples

The tool resolves each module authoritatively (no path globbing), judges
outcomes by artifacts, hard-fails when a declared module produces nothing, prints actionable diagnostics on failure
(the make.log tail for a build failure, or the dkms.conf gates evaluated
against the kernel config for a skip), and guards against name collisions.

CI path: debian/rules calls the tool

override_dh_auto_install invokes the tool with explicit, absolute paths after
the kernel, headers, and debug trees are staged:

$(CURDIR)/debian/scripts/bundle-dkms-modules.sh \
    --kver            "$$BASE" \
    --headers-dir     "$(CURDIR)/debian/linux-headers-$$BASE-qcom/usr/src/linux-headers-$$BASE" \
    --image-pkg-dir   "$(CURDIR)/$$PKG" \
    --dbg-pkg-dir     "$(CURDIR)/$$DBG_PKG" \
    --arch            "$(DKMS_ARCH)" \
    --objcopy         "$(OBJCOPY)" \
    --modules-manifest "$(CURDIR)/debian/dkms-modules"

dh_installmodules (called in override_dh_installdeb) wires the postinst
depmod that indexes extra/ on the device.

Developer path: run the tool standalone

A developer who has already staged the kernel trees can re-run just the bundling
step, without re-running the whole dpkg-buildpackage:

debian/scripts/bundle-dkms-modules.sh \
  --kver        <kernelrelease> \
  --headers-dir   /path/to/staged/linux-headers-<kernelrelease> \
  --image-pkg-dir /path/to/staged/linux-image-<kernelrelease>-qcom \
  --dbg-pkg-dir   /path/to/staged/linux-image-<kernelrelease>-qcom-dbg

--help documents the full CLI, prerequisites, and a host-arch note (the tool
builds with the host toolchain and is intended to run on a native arm64 host).

The manifest: debian/dkms-modules

A plain-text list of module names, one per line. Comments, blank lines, and CRLF
endings are tolerated. This is the single place that decides which modules are
built and bundled; the tool and debian/rules are untouched when it changes.

Adding a module is two lines:

1. Append the module name to debian/dkms-modules.
2. Add dkms and <name>-dkms (>= x.y.z) to Build-Depends in
   debian/control.in.

Module load policy

Blacklisting and load policy are orthogonal to this change. The bundled module is
installed under /lib/modules/<KVER>/extra/ and indexed by the standard depmod,
so to the loader it is an ordinary module: the usual controls apply by module name,
unchanged (a blacklist or install line in modprobe.d, or modprobe.blacklist=
or module_blacklist= on the kernel command line). The kernel package intentionally
ships no load policy of its own, because a blacklist is board and policy specific
while this package is shared across boards; that decision stays external to this
mechanism, at the image build stage.

Validation

CI (Ubuntu, resolute). Run
28193902324
(resolute, kernel 7.1.0-rc7-qcom-next-20260618). The Build kernel package
step builds and bundles the module from its *-dkms package:

[bundle-dkms]   Installed: .../lib/modules/.../extra/msm_kgsl.ko (stripped)
[bundle-dkms]   Debug:     .../linux-image-...-dbg/usr/lib/debug/lib/modules/.../extra/msm_kgsl.ko
[bundle-dkms] DKMS module bundling complete.

The packaged contents confirm the two-stage handling landed in both packages:

./lib/modules/.../extra/msm_kgsl.ko                  2,783,736 bytes  (kernel image, stripped)
./usr/lib/debug/lib/modules/.../extra/msm_kgsl.ko    1,271,360 bytes  (-dbg package)

All four packages (image, headers, dbg, dbgsym) built, and the
Upload .deb packages to S3 step now passes, so every step in the run is
green and the artifacts are published to
s3://.../pkg/temp/pkg-linux-qcom/28193902324-1/.

CI (Debian, trixie). Run
29125019996
(trixie, via Debusine). With kgsl-dkms now published to the Debusine workspace,
the Debian path satisfies the Build-Depends, the build runs to completion, and
msm_kgsl.ko is bundled into the linux-image exactly as on the Ubuntu path. All
Debusine build steps pass and the .debs publish to S3. Both distro families now
build and bundle the module end to end: Ubuntu (resolute, docker) and Debian
(trixie, Debusine).

Local (standalone tool, 18 of 18). The tool was exercised through its CLI
against shimmed leaf tools, so its real control flow, resolution, outcome
judgment, collision guards, and path layout all run:

Area	Cases
Happy path	module installed to extra/, debug written to the -dbg tree, strip ran on the shipped copy
Resolution failures	package not installed, multiple dkms.conf, missing PACKAGE_NAME
Outcome diagnosis	build failure prints the make.log tail; gated skip with config set, with config unset, and with no gates declared; compressed output reported
Collisions	in-tree name clash, duplicate bundled basename, duplicate manifest entry
Manifest	comment-only manifest skips cleanly, missing manifest fails closed, default path resolves correctly

Enablement status

This PR delivers the mechanism in full, with a reference module (kgsl) wired
in and validated end to end on both distro families (the two runs above).

A module can only be built on a family whose apt source publishes its *-dkms
package. For the reference module this is now satisfied on both: the source is
on Qualcomm Artifactory (the Ubuntu path) and, as of the rebuild in
qualcomm-linux/pkg-kgsl#62, on the Debusine workspace (the Debian path). Both
nightly families (trixie via Debusine, resolute via docker) build and bundle it
green, so the reference module stays wired in at merge.

The per-family principle still applies to future modules: turn a module on for
a family (a manifest line plus a Build-Depends entry) only once that family's
apt source carries the module source. Happy to sequence this whichever way the
maintainers prefer.

Requirements (R1 to R7)

#	Requirement
R1	One kernel package: kernel image plus every required out-of-tree module, built in the same run. No DKMS on the device.
R2	The kernel build declares a Build-Depends on the DKMS source packages. DKMS is a build-time tool, not a runtime mechanism.
R3	DKMS packages must not appear in Depends, Recommends, or Suggests of any binary package.
R4	Each module is compiled from source against the exact kernel produced in the same run. No cached artifact.
R5	A change to a DKMS package requires a kernel rebuild. Multiple changes can be batched into one rebuild.
R6	Each module's own CI stays independent and validates its own *-dkms package. The kernel CI only consumes it.
R7	The bundled module is handled like an in-tree module: stripped in the shipped package, debug symbols in the -dbg package.

Design decisions

Decision	Rationale
Build-time DKMS, not on-device	Single self-contained package, no toolchain or headers on the target, module pinned to the exact kernel (R1, R4).
DKMS as a build dependency only	The module is baked in, so nothing is resolved at install time and the runtime dependency graph stays clean (R3).
A standalone, documented tool	The logic lives in one file with a CLI, so debian/rules is a thin call, future changes touch one place, and the step is independently re-runnable.
Build against this run's staged headers	The module is compiled against the headers produced earlier in the same run, so it matches and loads against this kernel (R4).
Manifest driven	Which modules to build is separated from how to build them; a new module is two lines with no logic change.
Fail on a missing module	If a manifest module produces no artifact, the build fails rather than silently shipping without it. Never inferred from the module's own gates, so a misconfigured gate cannot silently drop a declared module.
Judge outcomes by artifacts, not exit codes	DKMS exit-code conventions vary across versions (a skip can exit 0). Success is a built module; failure diagnosis comes from the make.log and the dkms.conf gates.
Resolve identity from dpkg and dkms.conf	dpkg -L names the one dkms.conf the package ships; its PACKAGE_NAME/PACKAGE_VERSION are the tokens dkms keys on. No path globbing.
Private DKMS tree plus source symlink	Lets the build run rootless under fakeroot, away from the root-owned /var/lib/dkms.
In-tree-equivalent debug handling	Debug to the -dbg package via objcopy --only-keep-debug, then strip the shipped copy via strip --strip-debug.

Commits (13)

Bring-up
  declare the DKMS build-time dependency
  build the out-of-tree module and bundle it into the image
  drive the bundled modules from a manifest
  fail the build when a module yields no artifact
  pass dkms the uname -m architecture
  strip bundled modules and capture their debug
  resolve modules via dpkg and dkms.conf
  diagnose dkms build outcomes precisely
  guard against module name collisions when bundling
  extract bundling into debian/scripts/bundle-dkms-modules.sh

Post-extraction hardening
  fix a recipe syntax error in override_dh_auto_install
  fail closed when the manifest is missing
  harden the CLI and document the host-arch requirement

Not in this PR

• On-target validation: installing the package on a device and confirming the
  module loads and functions (modprobe, autoload). Hardware validation, owned by
  the device team.

Notes

• Target branch: qcom/debian/latest.
• All commits are DCO signed off and single authored.