[SegMind25]

Summary

Delivery: merging this puts everything on main, which is what sudo seglinux-upgrade reads, so existing installs pick it up (the upgrade now builds segctl too, see below). The merge commit carries [build iso] [build lite iso] so CI builds both editions.

Makes SegLinux fast for games without making the image heavier, on every init (OpenRC, runit, dinit, s6). Three parts:

1. Image defaults that are safe for everyone: a few sysctls, limits, shader-cache sizes, NVIDIA modeset, wine-staging, kernel parameters, and a fallback kernel.
2. seg game, a small addition to the existing seg Rust tool (a GameMode replacement with a readiness check and a hardware-aware driver installer). Binary: 567,536 B → 725,288 B (+157,752 B, +28 %), same release profile (opt-level = "z", LTO, codegen-units = 1, panic = "abort", strip). One new dependency, libc; all unsafe is in one file (game/proc.rs) and CI enforces that.
3. Docs: docs/gaming.md (Steam launch options, how to read seg game check, a benchmark method), tools/seg/README.md, README, a new CHANGELOG.md.

This PR is stacked on seg/rust-lean-overhaul, which is not merged and has no PR, so its commits (lean-down, seg itself, bug fixes) are part of this diff. The gaming work starts at cd1f78c; everything before it is that branch. docs/lean-audit.md has its measurements (full ISO −4.7 %, −475 MiB installed).

Every tweak and why

Image (installed by default)

Change	Where	Why
vm.max_map_count = 2147483642	80-seglinux-gaming.conf (already there)	Proton/Wine games crash with "out of memory" below ~1 M maps
kernel.split_lock_mitigate = 0	same (already there)	The kernel deliberately slows games that do split locks
vm.compaction_proactiveness = 0	same, new	Background memory defragmentation shows as stutter while a game allocates; on-demand compaction still works. What SteamOS sets
nofile hard 524288 → 1048576, nice -10 for @gamemode	limits.d	esync/fsync keep one fd per sync object; 1048576 is the kernel max. nice -10 lets seg game run raise a game's priority
Shader caches 10 GB: MESA_SHADER_CACHE_MAX_SIZE (was 4G), __GL_SHADER_DISK_CACHE_SIZE, __GL_SHADER_DISK_CACHE_SKIP_CLEANUP=1	/etc/profile.d (so every init; environment.d is systemd's)	With several games the 1 GB default evicts compiled shaders → recompiling stutter; NVIDIA deletes its cache when full unless told not to. Costs disk only; a value the user sets wins
nvidia_drm modeset=1 fbdev=1	/usr/lib/modprobe.d/seglinux-nvidia.conf	Needed by Wayland compositors and VT switching. Does nothing without NVIDIA's driver
wine → wine-staging	full profile	Staging patches (esync/fsync/NTSYNC, game fixes); provides wine. Resolves on Artix (CI)
transparent_hugepage=madvise	kernel cmdline (Setup) and seg game apply at boot	Huge pages only for programs that ask; always can stall on compaction. linux-zen starts with always, so the service switches always → madvise (it leaves never alone); found by booting the Lite image
amd_pstate=active	kernel cmdline (Setup), AMD CPUs only	The CPU picks clocks itself, guided by the energy hint seg game run sets. Ignored by kernels/CPUs without it
Fallback kernel	Setup, when online ([performance] fallback_kernel, default on)	Installs linux beside linux-zen (and the reverse); GRUB lists both. The kernel that runs is never removed
seg-game service (OpenRC, runit, dinit, s6)	segctl package, enabled by its install script	Applies the gaming sysctls and /dev/ntsync permissions at boot on every init
gamemode group created by segctl	install script	Needed for the sudoers rule below; Setup already adds users to it

Already in the repo and unchanged: linux-zen as the ISO kernel, NTSYNC module + udev rule, [lib32], mesa/vulkan-* and their lib32- versions, vulkan-tools, steam, gamescope, mangohud, winetricks, lutris, NVIDIA's open driver installed by Setup only when a Turing-or-newer GPU is found.

seg game (runtime, nothing permanent)

• seg game run -- CMD (Steam: seg game run -- %command%). While the game runs: governor + energy preference performance, AMD GPU power_dpm_force_performance_level = high, game nice -4 and best-effort I/O priority 0, screen saver held off (org.freedesktop.ScreenSaver.Inhibit over a hand-written minimal D-Bus client), optional pinning to the V-Cache chiplet of a two-chiplet X3D CPU (found from L3 sizes in /sys), shader-cache env, MangoHud/gamescope wrapping from per-game profiles. Everything is restored on exit, Ctrl+C, SIGTERM, SIGHUP and a panic of seg itself (a panic hook, since panic = "abort" skips destructors). Several games at once are handled (owners tracked by pid + start time, so a crashed game does not keep the boost on).
• seg game check: PASS/WARN/FAIL/SKIP with the exact fix under each: Vulkan, GPU driver, lib32 drivers, ntsync, vm.max_map_count, open files, kernel, fallback kernel, governor, amd-pstate, boost permission, hugepages, split lock, compaction, mitigations. Exit 1 on FAIL.
• seg game setup [--yes] [--games] [--lutris]: detects GPUs (/sys/class/drm + lspci) and lists/installs packages for those GPUs only. No NVIDIA card → no NVIDIA package.
• seg game profiles, per-game ~/.config/seg/games.toml (governor, pin, MangoHud, gamescope args, nice), matched by executable name; mistakes are reported with their line number.
• seg game apply (the service), seg game audio on|off (low-latency PipeWire, off by default), seg game unsafe-boost on|off (see safety), seg tune gaming.
• Presets, all off until asked: a MangoHud config, PipeWire drop-ins.

Safety notes

• mitigations=off is never a default. The only way to get it is sudo seg game unsafe-boost on --i-understand, which first prints a warning (Spectre/Meltdown-class protections; any program, including JavaScript, may read memory it must not), edits GRUB_CMDLINE_LINUX_DEFAULT, takes effect at the next boot. off undoes it; seg game check WARNs while it is on.
• No global unsafe tweaks. The CPU governor is never performance all day by default, only while a game runs. THP stays madvise. Nothing touches voltages or clocks.
• One narrow root helper. /etc/sudoers.d/seg-game lets the gamemode group run exactly seg game boost on <pid> [governor] and boost off <pid> as root. The helper rejects extra arguments, pid ≤ 1 and governor names with any character outside [a-z0-9_-], and only writes the cpufreq and amdgpu power files. A group member can therefore change the CPU governor and the AMD GPU power level and nothing else (the same trust the gamemode package asks for). visudo -cf runs in CI.
• The fallback kernel is never removed, by Setup, seg clean or anything else.
• Drivers only for hardware that is there: seg game setup and Setup read the PCI devices.
• Restore on crash: state lives in /run/seg (0700 dir, 0600 file, flock); a reboot clears everything anyway.
• unsafe is confined to game/proc.rs (9 libc calls, each with a SAFETY comment); CI fails if it appears anywhere else. No unwrap/expect/panic!/slice indexing outside tests (compile-time lints).

Deviations from the brief (please check)

1. Swappiness is not in the 80-…gaming sysctl file. With zram (the default) a high value is right, and Setup writes 180; a low value would make zram worse. seg tune gaming sets 10 for machines without zram (and 180 with it). Say if you want a fixed number in the file anyway.
2. lib32-mangohud is not in the Artix repositories (CI's pacman -Sp said so), so it is skipped: 32-bit games get no MangoHud overlay unless built from the AUR. Documented, and a test keeps it out of seg game setup.
3. NVIDIA before Turing: no proprietary driver is installed; those cards keep nouveau/NVK (NVIDIA's current branch dropped them). nvidia-dkms (non-open) is therefore not used anywhere.
4. docs/gaming.md, not docs/GAMING.md: that page already exists and a second file differing only in case would break checkouts on macOS/Windows. All gaming docs are there.
5. linux-zen is already the default ISO kernel, so "zen as a selectable entry" is implemented as the other kernel (linux) being installed beside it by Setup.
6. NVIDIA nvidia-settings power mode (PowerMizer) is not implemented in seg game run: it needs a running X/Wayland session API I could not test.

Verification

Run here and in CI:

• cargo fmt --check, cargo clippy -- -D warnings (with and without --all-targets), cargo test --locked: 187 tests in tools/seg (was 81 on the base branch; the new ones cover CPU/GPU detection against fake /sys and /proc trees in segctl/tests/fixtures — 7950X3D, a second-CCD V-Cache part, 7800X3D, ordinary AMD/Intel CPUs, a VM; AMD, NVIDIA Ada and Pascal, Intel Arc, a hybrid laptop, no GPU — and the TOML parsing, with line numbers in errors). Root workspace fmt/clippy/tests also pass (Setup changed).
• Release build and size: 725,288 B (CI prints it in the job summary).
• shellcheck clean on every script (the CI step is extended); visudo -cf on the sudoers rule.
• Package names on a real Artix container (pacman -Sp): all four package jobs (full on OpenRC/runit/dinit, Lite) pass, including wine-staging; they now also resolve every package seg game setup can choose (nvidia-open-dkms, nvidia-utils, lib32-nvidia-utils, nvidia-settings, vulkan-nouveau, …) on top of the image, via a pinned list (tests/setup-packages.txt) that a unit test keeps in step with the code.
• Real images, built in CI (a throwaway workflow on a branch that is deleted and not part of this PR): both editions build with build-in-container.sh (OpenRC, linux-zen) and were opened. Full: 2,890,530,816 B (the base branch's was 2,887,837,696 B: +2.7 MB for wine-staging and segctl's larger binary), about 6,672 MiB installed. Lite: 1,792.2 MiB installed. In both: the sudoers file is -r--r----- root/root and its content is the two commands only, the gamemode group exists, seg-game is enabled in default (OpenRC) and its runit/dinit/s6 files are there, the sysctl/limits/profile.d/modprobe files are installed. Full: wine-staging is in and plain wine is not, steam, gamescope, mangohud, winetricks, lutris, vulkan-tools, lib32-mesa, linux-zen, gamemode are in, no NVIDIA driver is on the image.
• Lite booted in QEMU/KVM (text console, logged in, commands typed and read back by OCR): max_map_count = 2147483642, compaction_proactiveness = 0, split_lock_mitigate = 0 and nofile hard = 1048576 are applied at boot; /dev/ntsync is crw-rw-rw-; seg-game, seg-tune, seg-zram are enabled and started; seg game check runs (9 pass, 3 to improve, 1 fail: no vulkaninfo on Lite by design); seg game run -- sleep 2 exits 0; seg game setup on the emulated VGA card says "no driver known" and lists the common Vulkan packages; seg tune gaming --dry-run shows its changes; seg doctor: no problems (that boot also found the shutdown-runlevel false positive and the hugepage gap below, both fixed afterwards).
• Found by that boot, fixed in this PR: (1) seg doctor called OpenRC's shutdown-runlevel services failed (fixed on the base branch); (2) transparent hugepages were always on linux-zen's live image, because madvise was only a GRUB parameter written by Setup: seg game apply (the seg-game service) now changes always to madvise at boot. Both fixes have unit tests; neither was booted again after the fix.
• sudo seglinux-upgrade only built the seglinux package, so an existing install would never have received seg, seg game, the services or the sudoers rule. It now builds segctl from the same source and installs both; CI builds this on an Artix container and checks the package, the group, the sudoers mode and syntax, the service files and seg game check/run --dry-run without a GPU.
• The benchmark summary script in the docs was checked against an independent Python calculation on synthetic frame times (it verifies the arithmetic only; no benchmark numbers are given anywhere, on purpose).
• Earlier on the base branch: seg against a real Artix container and a real dbus-daemon (screen-saver inhibit), restore-on-signal as an unprivileged user through a sudo shim.

Still untested

Nothing below was possible in the sandbox or in GitHub Actions (no GPU, VMs without cpufreq):

• No GPU anywhere, so no vkcube/vkmark and no game ran. seg game check's Vulkan parsing reads the deviceName = lines of vulkaninfo --summary from the documented format, not from a live capture.
• Real hardware paths: governor/EPP writes, AMD power_dpm_force_performance_level, /dev/ntsync on a real kernel, V-Cache pinning on a real X3D CPU (only fake sysfs trees written from the cache topology), amd_pstate driver detection. NVIDIA: nothing run on NVIDIA hardware (the DKMS step is unchanged apart from the headers; its plan text is unit-tested).
• The fixes after the image check (hugepages at boot, the upgrade also building segctl) were verified by unit tests and the CI Artix container, not by booting an image again.
• Setup on a real install: the fallback-kernel step, amd_pstate=active and THP parameters are covered by plan/unit tests only; grub-mkconfig listing both kernels is expected, not observed.
• Steam/Proton end to end: seg game run -- %command% was tested with ordinary commands and signals, not under Steam's reaper/pressure-vessel; profile matching of Proton command lines is unit-tested only. The screen-saver inhibit was tested against dbus-daemon, not a desktop's screensaver service.
• Other inits at run time: only OpenRC was booted. The runit, dinit and s6 seg-game definitions are shipped (file presence is checked in the built image) but not booted. The s6 definition (type/up) is untested in any way beyond shellcheck.
• The boost helper's concurrency (several games at once) is unit-tested, not exercised on a running system.
• The MangoHud options in the benchmark section (log_interval=0, autostart_log, no_display) and the low-latency PipeWire drop-ins were not run against MangoHud/PipeWire.
• No performance claim is made: whether seg game run helps on a given machine is for the reader to measure with the method in docs/gaming.md.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
seglinux	Ready	Preview	Oct 20, 2026 9:28pm UTC