Hardware Detection (linxira-hwd-detector)
Why it exists
Driver advice has to start from evidence that can be checked, not from guesses in a UI. Whether a GPU is integrated, discrete or passed through to a VM, and which CPU and virtualisation vendor are present, cannot be inferred from a window.
linxira-hwd-detector turns those facts into one read-only JSON document with a fixed
contract. The Hardware and Driver Manager maps facts to
policy; detection and policy stay separate.
Responsibilities
It owns:
- Read-only collection from fixed locations:
/sys/bus/pci/devices/*/{class,vendor,device},/sys/devices/virtual/dmi/id/{sys_vendor,product_name,chassis_type}and/proc/cpuinfo. - A
schema_version = 1document containingdetectormetadata (name, implementation version, upstream CHWD version),evidence(pci,dmi,cpu,virtualization), sorted and uniqueprofile_ids, and structuredwarningswithsourceandmessage. - Stable hardware-class IDs:
cpu.amd,cpu.intel,graphics.amd,graphics.intel,graphics.nvidia,graphics.hybrid,vm.hyperv,vm.qemu,vm.virtualbox,vm.vmware,vm.xen. - The full
lhwdCLI and the CHWD driver profiles installed under/var/lib/chwd/db.
It does not own:
- Package choice. The ID-to-package mapping, licence checks, kernel and DKMS preconditions all live in the manager.
- Kernel builds. Linxira ships the generic
linuxandlinux-ltskernels only. - Privilege escalation. Mutating
lhwdsubcommands only check the effective UID; they do not orchestrate Polkit or sudo.
Chain of responsibility: who reads, who plans, who changes
| Step | Performer | Changes the system? |
|---|---|---|
| Collect hardware facts (no-argument JSON) | linxira-hwd-detector |
Read-only, zero side effects |
| Facts → policy → plan | Hardware and Driver Manager | Read-only; plans go to the user state directory |
| Driver installation / service changes | Components system transaction service + Polkit | Privileged, with confirmation and a snapshot |
| Kernel and boot-state report | Kernel Manager | Read-only; plans go to the user state directory |
Detection stops at facts plus class IDs. Package names, licence decisions and execution order all belong downstream; the detector takes no part.
How to use
Read-only report
linxira-hwd-detector
Zero arguments prints the JSON report directly: no file writes, no package-manager calls,
no network. Both binaries share one entry branch keyed on argument count, so lhwd with no
arguments prints the same report; any argument routes to the full CLI below.
Contract highlights:
schema_versionversions the whole document;detector.versionversions the implementation. Both are validated strictly.- Missing evidence is
nullor an empty array plus a structured warning, never a guess. - Arrays are sorted and the document carries no timestamp field, so repeated runs on one machine produce byte-identical output.
The consumer is the manager, which calls the fixed path /usr/bin/linxira-hwd-detector
with a 10-second timeout and a 1 MiB output cap, then validates duplicate keys, name,
version and known class IDs.
Full CLI (lhwd)
lhwd --list # profiles available for detected devices
lhwd --list-installed # installed profiles
lhwd --list-all # every profile in the database
lhwd --check <profile> # check whether a profile matches this device
lhwd --autoconfigure # choose and install matching profiles for detected devices
lhwd --install <profile> # install a profile
lhwd --remove <profile> # remove a profile
--detail is only valid together with a listing option and adds fields. --force allows
reinstalling. --autoconfigure accepts an optional class ID (any when omitted); when no
device matches, it only warns and starts no transaction.
When root is required
- Not required:
linxira-hwd-detector(no arguments),lhwd --list,--list-installed,--list-all,--check. - Required:
lhwd --install,--remove, and--autoconfigurewhen a device is found. The source checks the effective UID before entering a package transaction and exits when it is not root.
The supported Linxira path is not lhwd: system changes go through
Components plans, confirmation and Polkit. lhwd is the retained full
CHWD tool surface, not the daily privilege entry point.
Known limitations
- Describes hardware classes only; package policy belongs to the manager.
- The package creates
/var/lib/chwd/scriptsbut does not install the/var/lib/chwd/scripts/chwdhelper thatlhwdcalls for--install,--removeand--autoconfigure. Those mutating subcommands therefore cannot complete as packaged; listing and checking are unaffected. - Detection covers a fixed set of evidence; adding a source means changing the contract.
- Profiles come from upstream CHWD 1.23.0 and assume upstream/Arch package names. The manager makes no per-device support claim from them.
Design notes
Upstream provenance and the fork point are in the repository's UPSTREAM.md; current
behaviour and boundaries are in the
linxira-hwd-detector README.
Maintainer conventions are in AGENTS.md. The licence is GPL-3.0-only.