Skip to content

Commit 593f97f

Browse files
ellie-diellie-di
committed
feat(kernel): publish kmod-nvidia-open and add packaging strategy doc
1 parent 4fb4592 commit 593f97f

2 files changed

Lines changed: 187 additions & 0 deletions

File tree

‎base/packages/base.packages.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2632,6 +2632,7 @@ packages = [
26322632
"kmod", # srpm: kmod
26332633
"kmod-devel", # srpm: kmod
26342634
"kmod-libs", # srpm: kmod
2635+
"kmod-nvidia-open", # srpm: kernel
26352636
"koji", # srpm: koji
26362637
"koji-builder", # srpm: koji
26372638
"koji-builder-plugins", # srpm: koji

‎docs/oss-kmod-packaging-strategy.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Open Source Out-of-Tree Kernel Module Packaging Strategy — Azure Linux 4.0
2+
3+
## Overview
4+
5+
Azure Linux 4.0 builds out-of-tree kernel modules (kmods) as **subpackages of the kernel RPM** rather than as standalone packages. This ensures tight coupling between the kernel binary and its companion modules — eliminating version skew, simplifying dependency resolution, and guaranteeing that modules are always compiled against the exact kernel headers they will run on.
6+
7+
## Architecture
8+
consider kmod-nvidia-open as an example:
9+
```
10+
kernel.comp.toml
11+
├── build.defines.nvidia_open_version = "595.58.03"
12+
├── source-files[] → kernel tarball, NVIDIA tarball
13+
├── overlays
14+
│ ├── [framework] kmod-macros.inc (Source5999)
15+
│ ├── [nvidia-open sources] .inc, modprobe.conf (Source6000-6002)
16+
│ └── [nvidia-open phases] spec-append-lines × 5 phases
17+
│
18+
└── Resulting kernel.spec (after overlays)
19+
├── %include kmod-macros.inc ← framework preamble
20+
├── %description → %include nvidia-open.inc (phase=package)
21+
├── %prep → %include nvidia-open.inc (phase=prep)
22+
├── %build → %include nvidia-open.inc (phase=build)
23+
├── %install → %include nvidia-open.inc (phase=install)
24+
└── %files → %include nvidia-open.inc (phase=files)
25+
```
26+
27+
### Key Files
28+
29+
| File | Purpose |
30+
|------|---------|
31+
| `kmod-<name>.inc` | Self-contained subpackage definition with phase-gated `%if` blocks |
32+
| `kmod-<name>.conf` | Module loading configuration (blacklists, options) |
33+
| `kernel.comp.toml` | Overlay definitions that wire everything together |
34+
35+
## Phase-Gated Include Pattern
36+
37+
RPM's `%include` directive is a preprocessor operation — it injects file contents literally into the spec at parse time. Since `%include` cannot appear inside macro bodies, we use a **phase-gating** pattern:
38+
39+
```spec
40+
# At each build phase, set the phase variable then include the kmod file:
41+
%global _kmod_phase build
42+
%global _kmod_name nvidia-open
43+
%include %{_sourcedir}/kmod-nvidia-open.inc
44+
```
45+
46+
Inside the `.inc` file, each section is guarded:
47+
48+
```spec
49+
%if "%{_kmod_phase}" == "build"
50+
# ... build commands ...
51+
%endif
52+
```
53+
54+
This allows a single `.inc` file to contain all phases of a kmod's lifecycle while only activating the relevant section at each point in the spec.
55+
56+
### Phase Execution Order
57+
58+
| Phase | Injection Point | Purpose |
59+
|-------|----------------|---------|
60+
| `package` | After `%description` | Declare `%package -n kmod-<name>`, Provides, Requires |
61+
| `prep` | End of `%prep` | Extract kmod source tarball |
62+
| `build` | End of `%build` | Compile modules against kernel build tree |
63+
| `install` | End of `%install` | Install `.ko` files, configs, licenses |
64+
| `files` | After `%files modules-extra-matched` | `%post`/`%postun` scriptlets and file list |
65+
66+
## Versioning Strategy
67+
68+
A kmod subpackage inherits the **kernel version** as its RPM Version/Release (e.g., `kmod-nvidia-open-6.18.5-1.8.azl4.x86_64.rpm`). The actual driver version is tracked via a virtual Provides:
69+
70+
```spec
71+
Provides: nvidia-open-kmod-version = %{nvidia_open_version}
72+
```
73+
74+
This means:
75+
- `Requires: kmod-nvidia-open` → gets whatever version matches the installed kernel
76+
- `Requires: nvidia-open-kmod-version = 595.58.03` → pins to a specific driver version
77+
78+
Consumer packages (e.g., `nvidia-cuda-driver`) should use the virtual Provides, not the RPM version directly.
79+
80+
## Adding a New kmod
81+
82+
### 1. Create the `.inc` file
83+
84+
```
85+
base/comps/kernel/kmod-<name>.inc
86+
```
87+
88+
Use `kmod-nvidia-open.inc` as a template. Implement all 5 phases with `%if "%{_kmod_phase}" == "<phase>"` guards.
89+
90+
### 2. Create supporting files
91+
92+
- `kmod-<name>.conf` — module loading config (blacklists, options)
93+
- Any patches specific to the kmod
94+
95+
### 3. Add source-files entry (if external tarball needed)
96+
97+
```toml
98+
[[components.kernel.source-files]]
99+
filename = "my-module-1.0.tar.gz"
100+
hash = "..."
101+
hash-type = "SHA256"
102+
origin = { type = "download", uri = "https://..." }
103+
```
104+
105+
### 4. Add overlays to `kernel.comp.toml`
106+
107+
```toml
108+
# Source registration (use Source6100+ range for the new kmod)
109+
[[components.kernel.overlays]]
110+
description = "Add kmod-<name>.inc to sources"
111+
type = "file-add"
112+
file = "kmod-<name>.inc"
113+
source = "kmod-<name>.inc"
114+
115+
[[components.kernel.overlays]]
116+
description = "Register kmod-<name> tarball as Sourcexxxx"
117+
type = "spec-insert-tag"
118+
tag = "Sourcexxxx"
119+
value = "my-module-1.0.tar.gz"
120+
121+
[[components.kernel.overlays]]
122+
description = "Register kmod-<name>.inc as Sourcexxxx++"
123+
type = "spec-insert-tag"
124+
tag = "Sourcexxx++"
125+
value = "kmod-<name>.inc"
126+
127+
# Phase injection (repeat for each phase)
128+
[[components.kernel.overlays]]
129+
description = "Run kmod-<name> 'package' phase"
130+
type = "spec-append-lines"
131+
section = "%description"
132+
lines = [
133+
"",
134+
"%global _kmod_phase package",
135+
"%global _kmod_name <name>",
136+
"%include %{_sourcedir}/kmod-<name>.inc",
137+
]
138+
139+
# ... repeat for prep, build, install, files ...
140+
```
141+
142+
### 5. Validate
143+
144+
```bash
145+
azldev comp render -p kernel # Check overlays apply cleanly
146+
azldev comp build -p kernel # Full build + kmod compilation
147+
```
148+
149+
## Source Number Allocation
150+
151+
| Range | Reserved For |
152+
|-------|-------------|
153+
| 5000–5099 | AZL kernel configs and certificates |
154+
| 5999 | kmod-macros.inc (framework) |
155+
| 6000–6099 | kmod-nvidia-open |
156+
| 6100–6199 | (next kmod) |
157+
| 6200–6299 | (next kmod) |
158+
159+
## RPM Output
160+
161+
A successful kernel build produces (among others) the following RPMs, consider kmod-nvidia-open as an example:
162+
163+
```
164+
kernel-6.18.5-1.8.azl4.x86_64.rpm
165+
kernel-core-6.18.5-1.8.azl4.x86_64.rpm
166+
kernel-modules-6.18.5-1.8.azl4.x86_64.rpm
167+
kmod-nvidia-open-6.18.5-1.8.azl4.x86_64.rpm ← kmod subpackage
168+
```
169+
170+
The kmod RPM contains:
171+
- `/lib/modules/%{KVERREL}/extra/nvidia/*.ko.xz` — compressed kernel modules
172+
- `/etc/modprobe.d/kmod-nvidia-open.conf` — blacklist conflicting modules
173+
- `/etc/depmod.d/kmod-nvidia-open.conf` — depmod override configuration
174+
- `/usr/share/licenses/kmod-nvidia-open/COPYING` — license file
175+
176+
## Constraints and Limitations
177+
178+
1. **RPM `%include` is a preprocessor directive** — it cannot be used inside `%define`/`%global` macro bodies, generated from Lua, or made conditional at the `%include` line itself (the `%if` must be inside the included file).
179+
180+
2. **No parametric dispatch** — each kmod requires explicit `%global` + `%include` lines per phase. You cannot loop over kmod names with a single macro call due to the `%include` limitation above.
181+
182+
3. **Build time** — each additional kmod adds compilation time to the kernel build. The NVIDIA open modules add ~5-10 minutes to a ~25 minute kernel build.
183+
184+
4. **Module compression** — the kernel spec's `%post` processing compresses `.ko` files to `.ko.xz`. The `%files` section must reference the compressed names.
185+
186+
5. **Architecture restrictions** — use `%ifarch x86_64 aarch64` guards in prep/build/install phases to skip kmod work on architectures where the module is not supported.

0 commit comments

Comments
 (0)