Skip to content

Commit b745d19

Browse files
AkarshHCLAkarshHCL
authored
Merge branch 'microsoft:3.0-dev' into 3.0-dev
2 parents 092f89e + 1a4c4f5 commit b745d19

35 files changed

Lines changed: 1300 additions & 54 deletions

‎.github/instructions/oot-modules.instructions.md‎

Lines changed: 315 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,315 @@
1+
---
2+
applyTo: 'SPECS*/**/*.spec'
3+
description: Always apply these instructions when editing `*.spec` files that build or repackage
4+
**out-of-tree (OOT) kernel modules**. Such specs are identifiable by the
5+
presence of `azl_kernel_*` macros (e.g., `azl_kernel_version`,
6+
`azl_kernel_hwe_version`).
7+
---
8+
9+
# Out-of-Tree (OOT) Kernel Module Spec File Conventions
10+
11+
## Instructions context
12+
13+
The specs to be analyzed with these instructions live under:
14+
15+
- `SPECS-NVIDIA/` and `SPECS-AMD/` — **unsigned** (build) specs.
16+
- `SPECS-NVIDIA-SIGNED/` and `SPECS-AMD-SIGNED/` — **signed** (repackaging) specs.
17+
18+
Above directory pairs are only examples - there may be additional directories for OOT specs,
19+
but they must follow the same conventions outlined in this document.
20+
21+
---
22+
23+
## 1. Kernel and Dependency Version Macros
24+
25+
### 1.1 Resolving the Target Kernel Version
26+
27+
Always use the `azl_kernel_*` macros provided by the build system. **Never** use
28+
`rpm -q` shell queries to discover the kernel version at build time.
29+
30+
- Example for the **default kernel**:
31+
32+
```rpm
33+
%global target_kernel_version_full %{azl_kernel_version}-%{azl_kernel_release}%{?dist}
34+
%global release_suffix _%{azl_kernel_version}.%{azl_kernel_release}
35+
```
36+
37+
- Example for the **HWE kernel**:
38+
39+
```rpm
40+
%global target_kernel_version_full %{azl_kernel_hwe_version}-%{azl_kernel_hwe_release}%{?dist}
41+
%global release_suffix _%{azl_kernel_hwe_version}.%{azl_kernel_hwe_release}
42+
```
43+
44+
### 1.2 Extending the Release Suffix with Additional Version Components
45+
46+
When the OOT module is tied to both a specific kernel **and** another package
47+
version (e.g., an NVIDIA driver version), the release suffix may be extended:
48+
49+
```rpm
50+
%global release_suffix _%{azl_kernel_version}.%{azl_kernel_release}.%{NVIDIA_DRIVER_VERSION}
51+
```
52+
53+
This is the exception, not the default. Use it only when the kernel module
54+
binary is specific to that additional dependency's exact version.
55+
56+
### 1.3 Resolving Non-Kernel Package Version
57+
58+
When the spec also depends on non-kernel packages (i.e., MOFED packages), resolve the version through the
59+
`azl_<pkg>_*` (i.e., `azl_mlnx_ofa_kernel_*`) macros:
60+
61+
- For the **default kernel**:
62+
63+
```rpm
64+
%{!?_mofed_full_version: %define _mofed_full_version %{azl_mlnx_ofa_kernel_version}-%{azl_mlnx_ofa_kernel_release}%{?dist}}
65+
```
66+
67+
Or simpler:
68+
```rpm
69+
%define _mofed_full_version %{azl_mlnx_ofa_kernel_version}-%{azl_mlnx_ofa_kernel_release}%{?dist}
70+
```
71+
72+
- For the **HWE kernel**:
73+
74+
```rpm
75+
%{!?_mofed_hwe_full_version: %define _mofed_hwe_full_version %{azl_mlnx_ofa_kernel_hwe_version}-%{azl_mlnx_ofa_kernel_hwe_release}%{?dist}}
76+
```
77+
78+
Or simpler:
79+
```rpm
80+
%define _mofed_hwe_full_version %{azl_mlnx_ofa_kernel_hwe_version}-%{azl_mlnx_ofa_kernel_hwe_release}%{?dist}
81+
```
82+
83+
---
84+
85+
## 2. Release Tag Format
86+
87+
### 2.1 Packages/Subpackages Containing OOT Modules
88+
89+
```rpm
90+
Release: [number][kernel_version_related_suffix]%{?dist}
91+
```
92+
93+
Example from `gdrcopy-hwe-kmod` subpackage in `gdrcopy-hwe.spec`.
94+
```rpm
95+
Release: %{_release}_%{target_azl_build_kernel_version}.%{target_kernel_release}.%{NVIDIA_DRIVER_VERSION}%{?dist}
96+
```
97+
98+
### 2.2 Packages/Subpackages NOT Containing OOT Modules
99+
100+
```rpm
101+
Release: [number]%{?dist}
102+
```
103+
104+
The `[kernel_version_related_suffix]` is **not needed** for subpackages that contain only
105+
kernel-independent components (usermode binaries, libraries, services, docs).
106+
107+
Example from `gdrcopy` base subpackage in `gdrcopy.spec`.
108+
```rpm
109+
Release: %{_release}%{?dist}
110+
```
111+
112+
### 2.3 Reusing the Release Number Across Subpackages
113+
114+
When the same release number must appear in multiple subpackages, encode it as a
115+
macro to avoid repetition:
116+
117+
```rpm
118+
%{!?_release: %define _release 3}
119+
```
120+
121+
Then reference it in each `Release:` tag:
122+
123+
```rpm
124+
# kmod subpackage (kernel-tied)
125+
Release: %{_release}%{release_suffix}%{?dist}
126+
127+
# service subpackage (kernel-independent)
128+
Release: %{_release}%{?dist}
129+
```
130+
131+
---
132+
133+
## 3. Subpackage Separation
134+
135+
### 3.1 Principle
136+
137+
Subpackages containing OOT kernel modules (`.ko` files) **must not** contain
138+
components that are not tied to a specific kernel version. Kernel-independent
139+
components include:
140+
141+
- Usermode binaries and scripts.
142+
- Shared libraries (`.so` files).
143+
- Systemd service units.
144+
- udev rules.
145+
- Configuration files not specific to the kernel module.
146+
- Documentation and man pages.
147+
148+
### 3.2 Reference Implementation
149+
150+
The `gdrcopy` spec family is the current exemplar for proper separation:
151+
152+
- `gdrcopy` — userspace library and test binaries.
153+
- `gdrcopy-service` — systemd service components.
154+
- `gdrcopy-dkms-src` — DKMS source for runtime compilation.
155+
- `gdrcopy-kmod` — prebuilt `gdrdrv.ko`, pinned to a specific kernel and NVIDIA
156+
driver version.
157+
158+
### 3.3 Known Gap
159+
160+
Most current specs (`cuda-open`, `cuda`, `amdgpu`, `amd-ama-driver`,
161+
`nvidia-vgpu-guest-driver`) bundle kernel modules and usermode components in a
162+
single package with `%{release_suffix}`. This is a known gap to be addressed in
163+
future refactoring. New specs **must** follow the separated pattern from the
164+
start.
165+
166+
---
167+
168+
## 4. Unsigned / Signed Spec Pair
169+
170+
Every OOT driver requires **two** specs:
171+
172+
### 4.1 Unsigned Spec (Build)
173+
174+
Located in `SPECS-NVIDIA/` or `SPECS-AMD/`. Responsibilities:
175+
176+
- Compile kernel modules from source.
177+
- Install unsigned `.ko` files (useful for dev testing with kernel lockdown
178+
disabled).
179+
- Place unlinked `.o` / `.ko` files in `kmod_o_dir` to be picked up by the
180+
signing pipeline.
181+
182+
### 4.2 Signed Spec (Repackaging)
183+
184+
Located in `SPECS-NVIDIA-SIGNED/` or `SPECS-AMD-SIGNED/`. Responsibilities:
185+
186+
- Take the unsigned RPM as `Source0`, referenced as
187+
`<name>-%{version}-%{release}.%{_arch}.rpm`.
188+
- Strip unsigned `.ko` files from the extracted contents.
189+
- Install signed `.ko` files provided as additional `Source` entries.
190+
- Repackage everything into the final RPM.
191+
- Repeat pre-/post-install scripts from the unsigned spec as needed for the subpackage they override from the unsigned spec.
192+
193+
**Mandatory** in signed specs — prevent RPM post-processing from stripping
194+
module signatures:
195+
196+
```rpm
197+
%define __os_install_post %{__os_install_post_leave_signatures} %{nil}
198+
```
199+
200+
Signed specs have an **empty `%build` section** — they never compile.
201+
202+
---
203+
204+
## 5. Build and Runtime Dependencies
205+
206+
### 5.1 Kernel Dependencies
207+
208+
```rpm
209+
# Build-time
210+
BuildRequires: kernel-devel = %{target_kernel_version_full}
211+
BuildRequires: kernel-headers = %{target_kernel_version_full}
212+
213+
# Runtime
214+
Requires: kernel = %{target_kernel_version_full}
215+
```
216+
217+
For GPU drivers, also add:
218+
219+
```rpm
220+
Requires: kernel-drivers-gpu = %{target_kernel_version_full}
221+
```
222+
223+
For **HWE kernel** variants, replace `kernel`/`kernel-devel`
224+
with `kernel-hwe`/`kernel-hwe-devel`, and
225+
`kernel-drivers-gpu` with `kernel-hwe-drivers-gpu`.
226+
227+
> **⚠ BUILD-SYSTEM LIMITATION — `kernel-headers`:**
228+
> Only the default `kernel-headers` package may appear as a `BuildRequires`.
229+
> Flavored variants (e.g., `kernel-hwe-headers`) **must not** be used because
230+
> `kernel-headers` is always pre-installed in the build chroot and conflicts
231+
> with any other flavor of the headers package. This restriction does **not**
232+
> apply to `kernel-devel` — using `kernel-hwe-devel` is correct and required
233+
> for HWE builds.
234+
235+
### 5.2 MOFED Dependencies
236+
237+
When InfiniBand / GPUDirect RDMA support is needed:
238+
239+
```rpm
240+
BuildRequires: mlnx-ofa_kernel-devel = %{_mofed_full_version}
241+
BuildRequires: mlnx-ofa_kernel = %{_mofed_full_version}
242+
BuildRequires: mlnx-ofa_kernel-modules = %{_mofed_full_version}
243+
BuildRequires: mlnx-ofa_kernel-source = %{_mofed_full_version}
244+
245+
Requires: mlnx-ofa_kernel = %{_mofed_full_version}
246+
Requires: mlnx-ofa_kernel-modules = %{_mofed_full_version}
247+
```
248+
249+
For **HWE kernel** variants, use `mlnx-ofa_kernel-hwe-*` package names and
250+
`%{_mofed_hwe_full_version}`.
251+
252+
---
253+
254+
## 6. Common Boilerplate
255+
256+
### 6.1 Standard Tags
257+
258+
```rpm
259+
Vendor: Microsoft Corporation
260+
Distribution: Azure Linux
261+
```
262+
263+
### 6.2 Changelog Format
264+
265+
```
266+
* Day Mon DD YYYY Full Name <email@microsoft.com> - VERSION-RELEASE
267+
- Description of change.
268+
```
269+
270+
Date format: `Day Mon DD YYYY` (e.g., `Tue Mar 24 2026`).
271+
272+
---
273+
274+
## 7. HWE Kernel Variant Naming Cheat Sheet
275+
276+
When creating an HWE variant of an existing spec, apply these substitutions
277+
throughout the entire spec:
278+
279+
| Default kernel | HWE kernel |
280+
|---|---|
281+
| `%azl_kernel_version` | `%azl_kernel_hwe_version` |
282+
| `%azl_kernel_release` | `%azl_kernel_hwe_release` |
283+
| `%azl_mlnx_ofa_kernel_version` | `%azl_mlnx_ofa_kernel_hwe_version` |
284+
| `%azl_mlnx_ofa_kernel_release` | `%azl_mlnx_ofa_kernel_hwe_release` |
285+
| `kernel` (package name) | `kernel-hwe` |
286+
| `kernel-devel` | `kernel-hwe-devel` |
287+
| `kernel-headers` | ~~`kernel-hwe-headers`~~ — **do not substitute for `BuildRequires`** (see §5.1 limitation) |
288+
| `kernel-drivers-gpu` | `kernel-hwe-drivers-gpu` |
289+
| `mlnx-ofa_kernel-*` | `mlnx-ofa_kernel-hwe-*` |
290+
| `_mofed_full_version` | `_mofed_hwe_full_version` |
291+
292+
---
293+
294+
## 8. Quick-Reference: Minimal Preamble Template
295+
296+
```rpm
297+
%global _enable_debug_package 0
298+
%global debug_package %{nil}
299+
%global __os_install_post /usr/lib/rpm/brp-compress %{nil}
300+
%global driver_version <DRIVER_VERSION>
301+
302+
%global target_kernel_version_full %{azl_kernel_version}-%{azl_kernel_release}%{?dist}
303+
%global release_suffix _%{azl_kernel_version}.%{azl_kernel_release}
304+
305+
# Only if MOFED is needed:
306+
%{!?_mofed_full_version: %define _mofed_full_version %{azl_mlnx_ofa_kernel_version}-%{azl_mlnx_ofa_kernel_release}%{?dist}}
307+
308+
Name: <package-name>
309+
Version: %{driver_version}
310+
Release: 1%{release_suffix}%{?dist}
311+
Summary: <summary>
312+
License: <license>
313+
Vendor: Microsoft Corporation
314+
Distribution: Azure Linux
315+
```

‎.github/instructions/spec.instructions.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
applyTo: 'SPECS*/**/*.spec'
3+
description: Always apply these instructions when editing `*.spec` files. They live under
4+
the `SPECS*` directories and their subdirectories. The exact directory structure may vary,
5+
but all spec files must follow the conventions outlined in this document.
6+
---
7+
8+
## Instructions context
9+
10+
- We're using `some-package` as a placeholder for the actual package name.
11+
- The spec file is placed in the `SPECS` or `SPECS-<SUBTYPE>` directory, e.g.:
12+
- `SPECS/some-package/some-package.spec`
13+
- `SPECS-NVIDIA/some-package/some-package.spec`
14+
- `SPECS-AMD/some-package/some-package.spec`
15+
16+
## General RPM spec instructions
17+
18+
- The spec file name and the directory name should be the same, if only one version of the package needs to be maintained.
19+
- Keep one spec subdirectory per package.
20+
21+
GOOD:
22+
- `SPECS/some-package/some-package.spec`
23+
- `SPECS/some-package-similar/some-package-similar.spec`
24+
25+
BAD:
26+
- `SPECS/some-package/some-package.spec`
27+
- `SPECS/some-package/some-package-similar.spec`
28+
- All packages must have a license file included through the `%license` macro in the `%files` section. Exceptions:
29+
- Subpackages that depend on another subpackage from the same spec, where that other subpackage already includes the license file. The expected end result of installing any package is that a license file for that package ends up being installed along with it.
30+
- "Metapackages", which don't build and install any of its own files but are a collection of run-time `Requires` dependencies.
31+
- If multiple versions need to be maintained, use versioned spec files names within the same directory. If you're adding a new version to an existing directory with a single spec file, keep the original spec file unchanged. Example:
32+
- `SPECS/some-package/some-package.spec`
33+
- `SPECS/some-package/some-package-v2.spec`
34+
- The `Name` tag in the spec file should match the spec file name except for the version suffix (if present). Example:
35+
- For `some-package.spec`, use `Name: some-package`
36+
- For `some-package-v2.spec`, use `Name: some-package`
37+
- Packages, which need their internal files (kernel or EFI modules for instance) signed, must have a separate signed spec file variant in its own `SPECS*-SIGNED` directory. The signed subdirectory and spec file should have the `-signed` suffix. Example:
38+
- For `SPECS-NVIDIA/some-package/some-package.spec` -> `SPECS-NVIDIA-SIGNED/some-package-signed/some-package-signed.spec`
39+
- The signed spec file must define only subpackages, which contain the signed files. The name of these subpackages must be identical to their unsigned counterparts. Example:
40+
- For `some-package-kmod` subpackage in the unsigned spec, define `some-package-kmod` subpackage in the signed spec as well.
41+
**NOTE**: since the signed spec only defines subpackages, either make `Name:` tag in the signed spec file match the subpackage name or define `%package -n <subpackage-name>` and `%files -n <subpackage-name>` explicitly in the signed spec file.
42+
- The signed specs DO NOT use the original sources. Instead, they use the RPM package built from the unsigned spec as the source of unsigned files and separately a `SourceX` entry for each of the signed files. No other source files are allowed. The files inside the original RPM should be extracted to the same installation paths as in the original RPM and then the signed files should replace the unsigned ones.
43+
- The signed subpackage must have the same pre- and post-install scripts as the unsigned subpackage (if any) to ensure proper installation and removal.
44+
45+
## Instructions specific to spec files building out-of-tree kernel modules
46+
47+
**IN ADDITION TO THESE INSTRUCTIONS**, follow instructions under `.github/instructions/oot-modules.instructions.md`.

‎README.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -33,11 +33,12 @@ Note: Support for the ISO is community based. Before filing a new bug or feature
3333
## Getting Help
3434
- Bugs, feature requests and questions can be filed as GitHub issues.
3535
- We are starting a public community call for Azure Linux users to get together and discuss new features, provide feedback, and learn more about how others are using Azure Linux. In each session, we will feature a new demo. The schedule for the upcoming community calls are:
36-
- 7/24/2025 from 8-9am (PST) [Click to join](https://teams.microsoft.com/l/meetup-join/19%3ameeting_ZDcyZjRkYWMtOWQxYS00OTk3LWFhNmMtMTMwY2VhMTA4OTZi%40thread.v2/0?context=%7b%22Tid%22%3a%2272f988bf-86f1-41af-91ab-2d7cd011db47%22%2c%22Oid%22%3a%2271a6ce92-58a5-4ea0-96f4-bd4a0401370a%22%7d)
37-
- 9/25/2025 from 8-9am (PST) [Click to join](https://teams.microsoft.com/l/meetup-join/19%3ameeting_ZDcyZjRkYWMtOWQxYS00OTk3LWFhNmMtMTMwY2VhMTA4OTZi%40thread.v2/0?context=%7b%22Tid%22%3a%2272f988bf-86f1-41af-91ab-2d7cd011db47%22%2c%22Oid%22%3a%2271a6ce92-58a5-4ea0-96f4-bd4a0401370a%22%7d)
38-
- 11/20/2025 from 8-9am (PST) [Click to join](https://teams.microsoft.com/l/meetup-join/19%3ameeting_ZDcyZjRkYWMtOWQxYS00OTk3LWFhNmMtMTMwY2VhMTA4OTZi%40thread.v2/0?context=%7b%22Tid%22%3a%2272f988bf-86f1-41af-91ab-2d7cd011db47%22%2c%22Oid%22%3a%2271a6ce92-58a5-4ea0-96f4-bd4a0401370a%22%7d)
39-
- 1/22/2026 from 8-9am (PST) [Click to join](https://teams.microsoft.com/l/meetup-join/19%3ameeting_ZDcyZjRkYWMtOWQxYS00OTk3LWFhNmMtMTMwY2VhMTA4OTZi%40thread.v2/0?context=%7b%22Tid%22%3a%2272f988bf-86f1-41af-91ab-2d7cd011db47%22%2c%22Oid%22%3a%2271a6ce92-58a5-4ea0-96f4-bd4a0401370a%22%7d)
40-
- 3/26/2026 from 8-9am (PST) [Click to join](https://teams.microsoft.com/l/meetup-join/19%3ameeting_ZDcyZjRkYWMtOWQxYS00OTk3LWFhNmMtMTMwY2VhMTA4OTZi%40thread.v2/0?context=%7b%22Tid%22%3a%2272f988bf-86f1-41af-91ab-2d7cd011db47%22%2c%22Oid%22%3a%2271a6ce92-58a5-4ea0-96f4-bd4a0401370a%22%7d)
36+
- 5/28/2026 from 8-9am (PST) [Click to join](https://teams.microsoft.com/l/meetup-join/19%3ameeting_ZDcyZjRkYWMtOWQxYS00OTk3LWFhNmMtMTMwY2VhMTA4OTZi%40thread.v2/0?context=%7b%22Tid%22%3a%2272f988bf-86f1-41af-91ab-2d7cd011db47%22%2c%22Oid%22%3a%2271a6ce92-58a5-4ea0-96f4-bd4a0401370a%22%7d)
37+
- 7/23/2026 from 8-9am (PST) [Click to join](https://teams.microsoft.com/l/meetup-join/19%3ameeting_ZDcyZjRkYWMtOWQxYS00OTk3LWFhNmMtMTMwY2VhMTA4OTZi%40thread.v2/0?context=%7b%22Tid%22%3a%2272f988bf-86f1-41af-91ab-2d7cd011db47%22%2c%22Oid%22%3a%2271a6ce92-58a5-4ea0-96f4-bd4a0401370a%22%7d)
38+
- 9/24/2026 from 8-9am (PST) [Click to join](https://teams.microsoft.com/l/meetup-join/19%3ameeting_ZDcyZjRkYWMtOWQxYS00OTk3LWFhNmMtMTMwY2VhMTA4OTZi%40thread.v2/0?context=%7b%22Tid%22%3a%2272f988bf-86f1-41af-91ab-2d7cd011db47%22%2c%22Oid%22%3a%2271a6ce92-58a5-4ea0-96f4-bd4a0401370a%22%7d)
39+
- 11/19/2026 from 8-9am (PST) [Click to join](https://teams.microsoft.com/l/meetup-join/19%3ameeting_ZDcyZjRkYWMtOWQxYS00OTk3LWFhNmMtMTMwY2VhMTA4OTZi%40thread.v2/0?context=%7b%22Tid%22%3a%2272f988bf-86f1-41af-91ab-2d7cd011db47%22%2c%22Oid%22%3a%2271a6ce92-58a5-4ea0-96f4-bd4a0401370a%22%7d)
40+
- 1/28/2027 from 8-9am (PST) [Click to join](https://teams.microsoft.com/l/meetup-join/19%3ameeting_ZDcyZjRkYWMtOWQxYS00OTk3LWFhNmMtMTMwY2VhMTA4OTZi%40thread.v2/0?context=%7b%22Tid%22%3a%2272f988bf-86f1-41af-91ab-2d7cd011db47%22%2c%22Oid%22%3a%2271a6ce92-58a5-4ea0-96f4-bd4a0401370a%22%7d)
41+
- 3/25/2027 from 8-9am (PST) [Click to join](https://teams.microsoft.com/l/meetup-join/19%3ameeting_ZDcyZjRkYWMtOWQxYS00OTk3LWFhNmMtMTMwY2VhMTA4OTZi%40thread.v2/0?context=%7b%22Tid%22%3a%2272f988bf-86f1-41af-91ab-2d7cd011db47%22%2c%22Oid%22%3a%2271a6ce92-58a5-4ea0-96f4-bd4a0401370a%22%7d)
4142

4243
## Trademarks
4344

0 commit comments

Comments
 (0)