tpt-linux-hw

TPT Solutions — Linux Hardware Discovery & Event Management

A workspace of small, focused, pure-Rust crates that provide a unified, async-friendly abstraction over Linux hardware discovery: sysfs walking, block/PCI/USB enumeration, ACPI table parsing, netlink udev event streaming, and udev rule evaluation — replacing the fragmented lshw/lsblk/lspci/ lsusb + libudev suite with one consistent API.

Design principles

• Pure Rust for new surface area — async netlink events and unified enumeration are implemented without FFI; well-covered ground is not reinvented.
• Resilient to kernel quirks — sysfs parsing uses Option<T> and graceful degradation; malformed content never panics.
• Async event streaming — hardware events are exposed as tokio::sync::mpsc streams.
• Explicit privilege model — every privileged operation surfaced as a distinct, well-typed error variant rather than a generic I/O error.

Crates

Crate	Description	Privilege
tpt-l-sysfs-walker	Traverse /sys, resolve symlink trees, parse uevent/attributes	unprivileged
tpt-l-mountinfo	Zero-alloc parser for /proc/self/mountinfo and /etc/fstab	unprivileged
tpt-l-hwdb-reader	Pure-Rust reader for the systemd hwdb binary trie	unprivileged
tpt-l-pci-enumerator	Enumerate /sys/bus/pci + config space	unpriv (sysfs) / CAP_SYS_ADMIN (config)
tpt-l-usb-enumerator	Enumerate /sys/bus/usb + descriptors	unprivileged
tpt-l-block-device	Unified block-device abstraction	unprivileged
tpt-l-netlink-udev	udev events over NETLINK_KOBJECT_UEVENT	may need CAP_NET_ADMIN
tpt-l-udev-rules	Parser/evaluator for /etc/udev/rules.d	unpriv (parse); RUN{} caller-controlled
tpt-l-acpi-parser	ACPI table discovery + static field extraction	unprivileged
tpt-l-hw-cli	Unified CLI (list pci/usb/block/mounts, watch)	see subcommands

Building

cargo build --workspace
cargo test --workspace

Usage

The tpt-hw binary unifies discovery:

# Human-readable listings
tpt-hw list pci
tpt-hw list usb
tpt-hw list block
tpt-hw list mounts

# Structured output
tpt-hw list pci --json
tpt-hw list usb --yaml

# Live event stream (Linux; needs NETLINK_KOBJECT_UEVENT)
tpt-hw watch
tpt-hw watch --json

# Opt into privileged operations (e.g. raw PCI config space) — explicit & acknowledged
tpt-hw list pci --privileged

Note: --privileged only enables operations that require CAP_SYS_ADMIN / root. Unprivileged enumeration works without it.

Status

Phase	Status
0 — Workspace bootstrap	done
1 — Core discovery & parsing	done
2 — Device enumerators	done
3 — Event handling & rules	done (ACPI AML interpreter deferred to Milestone B)
4 — CLI integration	done
5 — Docs & polish	done

License

Licensed under either of MIT or Apache-2.0 at your option.