Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 16 additions & 7 deletions docs/install-any-distro.md
Original file line number Diff line number Diff line change
Expand Up @@ -213,7 +213,7 @@ that stays on its distribution's kernel only needs the second and third:

The three driver/config packages are the same set in all three families, and that set alone is a
complete install for a machine that keeps its distribution's kernel — proved as its own path
(`mk-kernel-packages.sh --skip-kernel`, then `pkg-proof.sh`): 22 rows PASS with the kernel rows marked
(`mk-kernel-packages.sh --skip-kernel`, then `pkg-proof.sh`): 24 rows PASS with the kernel rows marked
skipped, ending with the distribution's own `amdxdna` restored. They install to
`/lib/modules/<ver>/updates/` (Debian, Arch) or `/extra/` (Fedora) through dkms, which is in front of
the in-tree `amdxdna`, and uninstalling the package puts the in-tree driver back — measured, not assumed:
Expand Down Expand Up @@ -407,6 +407,15 @@ registry model, since this Lemonade version has no local-file registration):

## What has been measured where

The row counts below move whenever a row is added, and they are the numbers a reader reproduces by running
`scripts/pkg-proof.sh` themselves. **Last reconciled 2026-11-08 at `345deef7` (on `main`)**: deb 34 and Arch
32 were re-run at that commit; Fedora 32 and openSUSE 32 were measured earlier the same day on the same
harness — the script at `345deef7` is `e351cce4`'s (#1514), which contains #1495's collision rows and
#1511's `mkdir -p` guard, so all four numbers come from one harness. Cite a commit **on `main`**, never a PR
head: an earlier version of this note cited `421487af`, which is `refs/pull/1514/head` and predates #1511 —
a harness in which the Arch collision rows could fail for want of a directory. If you add a row, re-run and
update all four.

| claim | where | result |
|---|---|---|
| **each family installs, runs and uninstalls** | clean containers, 2026-11-06, from the `rc-2026-11-06-c31` payload: `fedora:latest` (`dnf`, rpm 6.1.0, glibc 2.44), `opensuse/tumbleweed:latest` (`zypper`), `archlinux:latest` (`pacman -U`, pacman 7.1.0), `ubuntu:26.04` (`apt-get`) | all four: install, `1bit-engine --version` prints `1bit 0.0.1`, the shim `/opt/1bit/engine/lemonade-bin/llama-server --version` prints `version: 1 (32559003)` / `built with Clang 24.0.0 for Linux x86_64`, then remove and `/opt/1bit/engine/1bit` is gone. Fedora refused the first build and that was the payload's fault, not dnf's: the package listed `/usr/bin` and `/usr/lib` at 0755 while Fedora's `filesystem` owns them at 0555 (`file /usr/bin from install of 1bit-engine-2026.45-1.x86_64 conflicts with file from package filesystem-3.18-59.fc45.x86_64`); `scripts/pack-distro.sh` now normalises the payload's modes and leaves the distributions' own skeleton out of the file list |
Expand All @@ -422,19 +431,19 @@ registry model, since this Lemonade version has no local-file registration):
| the shim is the engine's own wrapper | `1bit/lemonade-hrx` from this repo's package (`scripts/package-linux.sh`) | it runs `1bit serve --print-backend-env` and then `exec`s the engine with serve's environment and defaults; `lemonade-bin/llama-server` is a symlink to it |
| the recipe's env for its backend is one variable | this tree, `src/cpp/server/backends/hrx/hrx_server.cpp` `build_server_environment()` | Lemonade passes its backend `GGML_DISABLE_VULKAN=1` only — which is why the wrapper, not our binary, has to be what the recipe starts |
| `amdxdna-dkms` from the PPA drags kernel bits | clean container, `apt-get -s install amdxdna-dkms` | `dkms`, `build-essential`, `linux-headers-7.0.0-42-generic`, `linux-headers-generic`, `amdxdna-dkms` |
| the driver packages install, build and uninstall on Debian/Ubuntu | clean `ubuntu:26.04` container, `scripts/pkg-proof.sh deb` | all 31 rows PASS: dkms builds both modules against `7.0.0-43-generic`, `modprobe --show-depends amdxdna` resolves to `/lib/modules/7.0.0-43-generic/updates/dkms/amdxdna.ko.zst` (in front of the in-tree one), the kernel debs' `vmlinuz` is `sbverify`-clean against the certificate in `1bit-npu-config`, purge removes the /etc files |
| the same on Fedora | clean `fedora:latest` (fc45) container, `scripts/pkg-proof.sh rpm` | all 29 rows PASS: modules under `/lib/modules/7.2.15-300.fc45.x86_64/extra/`, kernel rpms install `1bit-kernel` + `1bit-kernel-devel` with the build symlink at `/usr/src/kernels/7.4.0-rc1-1bit`, uninstall leaves nothing |
| the same on Arch | clean `archlinux:latest` container, `scripts/pkg-proof.sh arch` | all 29 rows PASS: the pacman dkms hook builds both modules at install time, `linux-1bit` + `linux-1bit-headers` install with the build tree at `/usr/lib/modules/7.4.0-rc1-1bit/build` and `/etc/mkinitcpio.d/1bit.preset` |
| the driver packages install, build and uninstall on Debian/Ubuntu | clean `ubuntu:26.04` container, `scripts/pkg-proof.sh deb` | all 34 rows PASS: dkms builds both modules against `7.0.0-43-generic`, `modprobe --show-depends amdxdna` resolves to `/lib/modules/7.0.0-43-generic/updates/dkms/amdxdna.ko.zst` (in front of the in-tree one), the kernel debs' `vmlinuz` is `sbverify`-clean against the certificate in `1bit-npu-config`, purge removes the /etc files |
| the same on Fedora | clean `fedora:latest` (fc45) container, `scripts/pkg-proof.sh rpm` | all 32 rows PASS: modules under `/lib/modules/7.2.15-300.fc45.x86_64/extra/`, kernel rpms install `1bit-kernel` + `1bit-kernel-devel` with the build symlink at `/usr/src/kernels/7.4.0-rc1-1bit`, uninstall leaves nothing |
| the same on Arch | clean `archlinux:latest` container, `scripts/pkg-proof.sh arch` | all 32 rows PASS: the pacman dkms hook builds both modules at install time, `linux-1bit` + `linux-1bit-headers` install with the build tree at `/usr/lib/modules/7.4.0-rc1-1bit/build` and `/etc/mkinitcpio.d/1bit.preset` |
| the dkms source reproduces the driver this box runs | `scripts/mk-kernel-packages.sh` payload built in a container against `7.0.0-43-generic` | `srcversion EE1F36A2B9BA294CE11AD80`, the srcversion of the `amdxdna.ko` installed at `/lib/modules/7.4.0-rc1-1bit/updates/` — the package's source *is* the fleet's series |
| the kernel the packages ship is the kernel this box runs | `linux-image-7.4.0-rc1-1bit_7.4.0~rc1-1_amd64.deb` payload vs `/boot/vmlinuz-7.4.0-rc1-1bit` | `sha256 6f3c6764…` in both, and `sbverify --cert MOK-Kernel.der` reports `Signature verification OK` |
| the amdxdna floor is really 6.10 | clean `ubuntu:24.04` container, headers `6.8.0-149-generic`, this page's packages | `dkms build` refuses with the declared exclusive rule (`rc=77`, "should not be built"), and with the floor bypassed the driver does not compile: `amdxdna.h:32: macro "__assign_str" requires 2 arguments, but only 1 given` — the 6.10 trace-event API. `ec-su-axb35-dkms` builds on the same headers (`380 440 B`), so only the NPU driver has the floor |
| a weekly release tag works in all three families, and upgrades | `scripts/mk-kernel-packages.sh <out> 2026.45.0 --skip-kernel`, each family's own tool, in `fedora:latest` / `ubuntu:26.04` / `archlinux:latest` | deb `0.18.0-1 < 0.18.0-2026.45.0` (dpkg), rpm `0.18.0-1 < 0.18.0-2026.45.0` (rpmdev-vercmp), arch `vercmp` `-1`; each installs over the previous package (`rc=0`) and reports `0.18.0-2026.45.0` afterwards, with one `/usr/src/amdxdna-1bit-0.18.0` left on deb — no stale duplicate source tree |
| uninstalling really restores the in-tree driver, in all three families | `scripts/pkg-proof.sh`, each family in its container, after the purge | the in-tree module is gone from the tree while ours is installed (dkms archives it to `/var/lib/dkms/<pkg>/original_module/`), and after removal both `modprobe --show-depends amdxdna` and the file are back on the `kernel/` path: `amdxdna.ko.zst` on Ubuntu and Arch, `amdxdna.ko.xz` on Fedora. Same three containers as the install rows, `PROOF-RC=0` |
| uninstalling the kernel package leaves the machine as it found it | `scripts/pkg-proof.sh`, each family in its container, after removing the kernel package | deb `dpkg -P linux-image` rc=0, rpm `rpm -e 1bit-kernel-devel 1bit-kernel` rc=0, arch `pacman -R linux-1bit-headers linux-1bit` rc=0; `/boot/vmlinuz-7.4.0-rc1-1bit` (or `/boot/vmlinuz-1bit` on Arch) is gone and the module tree under `modules/7.4.0-rc1-1bit` has **0 files** left. deb **29/29**, rpm **27/27**, arch **27/27** rows PASS, `PROOF-RC=0` |
| uninstalling the kernel package leaves the machine as it found it | `scripts/pkg-proof.sh`, each family in its container, after removing the kernel package | deb `dpkg -P linux-image` rc=0, rpm `rpm -e 1bit-kernel-devel 1bit-kernel` rc=0, arch `pacman -R linux-1bit-headers linux-1bit` rc=0; `/boot/vmlinuz-7.4.0-rc1-1bit` (or `/boot/vmlinuz-1bit` on Arch) is gone and the module tree under `modules/7.4.0-rc1-1bit` has **0 files** left. deb **34/34**, rpm **32/32**, arch **32/32** rows PASS, `PROOF-RC=0` |
| a hand-written limits file does not block the install | `scripts/pkg-proof.sh`, all three families | with a pre-existing `99-amdnpu-memlock.conf` (65536, the file this fleet's own box wrote by hand on 2026-10-12) the install succeeds and both files are present, and removing the package leaves the hand-written one intact. Measured on the shipped `90-` name; at the original `99-` name the same scenario **failed** — `dpkg` rc=1 on the conffile conflict, and a purge then deleted the user's file. Cleaned up after the row, since a `99-` file legitimately overrides our `90-` and would change what the memlock rows below measure |
| the memlock file is honoured, not just present | `scripts/pkg-proof.sh`, all three families, running the container with `--cap-add=sys_resource` | a probe login with the file rewritten to `4096` came back with exactly `4096` (lowering always works, so that value can only come from the file), and with the shipped file back the same login reports `ulimit -l: unlimited`. Without `CAP_SYS_RESOURCE` — which a container's default set excludes — raising the hard limit fails and the session keeps the container's `8192`, which is the container, not the package |
| the distribution-kernel path, on its own | clean `ubuntu:26.04` container, packages built with `--skip-kernel`, `scripts/pkg-proof.sh deb` | 22 rows PASS and one `INFO no kernel packages in this dir` (the kernel rows skip themselves instead of failing): install, config, memlock reaching a login session, dkms building both modules against `7.0.0-43-generic`, `amdxdna` resolving to `updates/dkms`, uninstall, and the distribution's in-tree `amdxdna` back in place. This is the path a user on their own kernel takes |
| the distribution-kernel path, on its own | clean `ubuntu:26.04` container, packages built with `--skip-kernel`, `scripts/pkg-proof.sh deb` | 24 rows PASS and one `INFO no kernel packages in this dir` (the kernel rows skip themselves instead of failing): install, config, memlock reaching a login session, dkms building both modules against `7.0.0-43-generic`, `amdxdna` resolving to `updates/dkms`, uninstall, and the distribution's in-tree `amdxdna` back in place. This is the path a user on their own kernel takes |
| the engine package and this set install on the same machine | clean `ubuntu:26.04` container, `scripts/pkg-proof.sh coexist`, engine `1bit-engine_2026.11.02-1_amd64.deb` | all 26 rows PASS: the engine installs alone, this set installs **over it** with `dpkg` reporting no file conflict, `/usr/share/1bit` holds both (`lemonade-config-fragment.json` from the engine, `mok/MOK-Kernel.der` from `1bit-npu-config`) with each file attributed to its own package, the engine still runs (`1bit 0.0.1`), both dkms modules build, purging this set leaves the engine's files intact, and the engine purges last. Neither `scripts/pack-proof.sh` (the engine) nor the rows above (this set) install both, so this is the combination nobody had tried |
| the same `.rpm` installs on openSUSE Tumbleweed | clean `opensuse/tumbleweed` container, `scripts/pkg-proof.sh rpm` | **all 29 rows PASS**, `rc=0` — the same file Fedora takes, installed by `rpm`/zypper with no per-distro package: dkms builds both modules against `7.3.1-1-default`, `amdxdna` resolves to the dkms build ahead of the in-tree one, the kernel rpm installs and removes cleanly, the distribution's own module is restored. Two container facts, not package facts: openSUSE keeps headers in `/usr/src/linux-<ver>-obj/<flavour>` (so the harness finds the version through `/lib/modules/<ver>/build/Makefile`, never a vendor path), and the container needs `kernel-default` + `udev` for the in-tree-module and `udevadm` rows to have anything to look at |
| the same `.rpm` installs on openSUSE Tumbleweed | clean `opensuse/tumbleweed` container, `scripts/pkg-proof.sh rpm` | **all 32 rows PASS**, `rc=0` — the same file Fedora takes, installed by `rpm`/zypper with no per-distro package: dkms builds both modules against `7.3.1-1-default`, `amdxdna` resolves to the dkms build ahead of the in-tree one, the kernel rpm installs and removes cleanly, the distribution's own module is restored. Two container facts, not package facts: openSUSE keeps headers in `/usr/src/linux-<ver>-obj/<flavour>` (so the harness finds the version through `/lib/modules/<ver>/build/Makefile`, never a vendor path), and the container needs `kernel-default` + `udev` for the in-tree-module and `udevadm` rows to have anything to look at |
| the dkms package signs with the machine's own MOK, and what happens without one | clean `ubuntu:26.04` container, headers `7.0.0-43-generic`, `amdxdna-1bit-dkms` 0.18.0-1, paired with and without a MOK at `/var/lib/shim-signed/mok` | with one: `scripts/sign-file`, sha512, `modinfo -F signer` = that certificate's CN and a `sig_key`; without: `modules won't be signed`, `signer` and `sig_key` empty. So the package chains to the user's key — and on a Secure Boot machine with no MOK of its own the module installs, builds, and refuses to load |
| the shipped driver answers a known answer on the NPU | this box, `npu-hold`, `1bit serve --device npu` on Qwen3-0.6B, `/v1/completions` greedy, twice | load 2.2 s, `The capital of France is` → **` Paris. The capital of Italy is Rome. The capital of Spain is Madrid.`** identically on both runs (56.9 and 50.7 tok/s), 0 `amdxdna` lines in the two windows, and the loaded module is `srcversion EE1F36A2B9BA294CE11AD80` — the build this package's source produces. No install, no `modprobe`, no udev reload |
Loading