Skip to content

LordOS — a free, fast and secure GNU/Linux distribution based on Debian, with its own desktop environment: display server and Wayland compositor in C, a React UI engine on QuickJS, and private native apps.

Docs: firmware and displays (UEFI and legacy BIOS), VM audio, VMware notes, 0.8.1 changelog

Federico Pereirab25d9c07d08e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a0deab9..a8d6faf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,6 +19,10 @@ of the matching [GitHub release](https://github.com/lordbasex/LordOS/releases),
lets you allow all users or only administrators. Root never logs in (`PermitRootLogin no` in a
drop-in shipped by the `lordos` package). The Raspberry Pi image's `ssh` switch file keeps
working and shows up as on ([docs/REMOTE.md](docs/REMOTE.md#remote-login-ssh)).
+- **Guest tools on VMware.** The ISO (and so every installed system) ships `open-vm-tools`:
+ shutdown and restart from the hypervisor, time sync and the guest's IP address. Its services only
+ run under VMware. Shared clipboard and automatic screen resize are not supported yet
+ ([docs/ISO.md](docs/ISO.md#firmware-and-displays)).
### Changed
@@ -32,6 +36,15 @@ of the matching [GitHub release](https://github.com/lordbasex/LordOS/releases),
sent from "This computer" to the place and received back, more and faster with the rate; idle
arcs are dimmed. Reduce motion shows still markers instead; the animation runs at 12 frames per
second, only on screen, and stops when the window is minimized.
+- **More audio headroom in virtual machines.** When LordOS runs in a VM, emulated sound outputs
+ get 8 periods of 1024 frames, 8192 frames of headroom and interrupt-driven scheduling (a
+ WirePlumber rule that only matches in a VM; real hardware keeps its low latency). On VMware this
+ stopped YouTube stuttering in Chromium ([docs/SOUND.md](docs/SOUND.md#virtual-machines-081)).
+- **Background work yields to the desktop after login.** Mail sync runs at nice 19 with idle I/O
+ and the thumbnail worker at the lowest I/O priority, so they don't compete with sound and the
+ first windows.
+- **The input level meter in Settings → Sound** reads a normal 48 kHz stream instead of a 25 Hz
+ peak stream, which in PipeWire ran as a node with a quantum of 1.
### Fixed
@@ -57,6 +70,16 @@ of the matching [GitHub release](https://github.com/lordbasex/LordOS/releases),
- **The Network tab's detail panel no longer hides values under its scroll bar.** The panel keeps
a strip for the bar, and a label and value that don't fit on one line go on two instead of
running over the next row (es/en/pt, right to left, minimum window size).
+- **The live ISO boots with legacy BIOS again.** 0.8.0 triple-faulted on VMware (and hung at the
+ boot menu on QEMU's VMware-compatible display) when booting with BIOS firmware: GRUB's graphical
+ terminal corrupted its own memory at 640×480 with the theme's proportional font. The theme now
+ uses GRUB's fixed-width font for the terminal and BIOS boots ask for 1024×768 first; UEFI is
+ unchanged. Installed systems get the same theme fix
+ ([docs/ISO.md](docs/ISO.md#firmware-and-displays)).
+- **No silent black screen without a KMS display.** When there is no display device with kernel
+ modesetting (for example QEMU's VMware-compatible display), the text console now says so and
+ suggests a display that works; `vmwgfx` only loads on VMware itself, so the console stays
+ visible elsewhere.
## [0.8.0-beta] - 2026-10-18
diff --git a/docs/GPU.md b/docs/GPU.md
index 0736c43..21d66d3 100644
--- a/docs/GPU.md
+++ b/docs/GPU.md
@@ -37,6 +37,19 @@ and its buffers and the apps' dmabufs become framebuffers with `DRM_IOCTL_MODE_A
Diagnostics: `LORD_GPU_DEBUG=1` shows the dmabuf formats, failing imports and the frames sent by
direct scanout. The log says `gpu: GPU composition (renderer…)` or why not.
+**VMware virtual machines** (VMware SVGA, the `vmwgfx` kernel driver). `vmwgfx` is not in the
+list of plain drivers, so Mesa is loaded: with the machine's 3D acceleration on, Mesa's `svga`
+driver (`vmwgfx_dri.so`, in `libgl1-mesa-dri`, which the ISO ships) is the renderer and lord-server
+composites on the GPU (`GL_RENDERER` starts with `SVGA3D`); with 3D off, Mesa falls back to
+llvmpipe and lord-server to the CPU path. Which one ran is in the session log: in a LordOS
+Terminal, `grep gpu: ~/.cache/lordos/session.log` (for example `gpu: GPU composition (SVGA3D; …)`
+or `gpu: the renderer is software (llvmpipe …): CPU composition`). Not verified: the Proxmox test
+machines' "VMware compatible" display is QEMU's 2D-only `vmware-svga`, which `vmwgfx` refuses
+(since 0.8.1 it isn't even loaded there; see `ISO.md`, "Firmware and displays"), so only the
+presence of `vmwgfx_dri.so` in the image was checked. GPU composition with VMware's 3D, and why
+lord-server used ~35 % CPU with a video playing on the user's VMware machine, still need that log
+line from a real VMware guest.
+
## How it composites
- **The UI** (React → CPU canvas) is a fullscreen texture. Per frame only what changed (the
diff --git a/docs/ISO.md b/docs/ISO.md
index 4a5462d..fa1f1a8 100644
--- a/docs/ISO.md
+++ b/docs/ISO.md
@@ -44,6 +44,63 @@ motherboard. It works with **UEFI** and with **BIOS/Legacy**. **Secure Boot** ha
The GRUB menu itself is in English (GRUB's default). Every entry except safe mode boots with the
boot splash (`splash`); safe mode boots in text (`nosplash`).
+## Firmware and displays
+
+The ISO boots with **UEFI** and with **legacy BIOS** (a hybrid image from `grub-mkrescue`: El
+Torito for BIOS and `efi.img` for UEFI). Secure Boot has to be off. For virtual machines the
+smoothest setup is UEFI firmware, 4 GB of memory, 2–4 processors and the "Debian 64-bit" guest
+type; legacy BIOS works too since 0.8.1.
+
+**The 0.8.0 legacy BIOS bug.** On VMware Fusion with BIOS firmware (2 GB, 2 vCPUs, SVGA) the
+machine triple-faulted when the menu's 5 s timeout fired; with UEFI it booted. On Proxmox with
+SeaBIOS and the "VMware compatible" display, GRUB hung right after drawing the menu (the CPU
+halted in real mode, keys did nothing); with standard VGA it booted. Cause, found by bisecting the
+GRUB configuration on VM 123 with small test ISOs (kernel and initrd only):
+- with BIOS, GRUB draws through VBE, and `gfxmode=auto` falls back to **640×480** when the
+ display reports no EDID (both VMware's SVGA and QEMU's `vmware-svga`; VMware's log shows the
+ 640×480 mode being set right before the fault);
+- at 640×480 GRUB's graphical terminal (`gfxterm`) corrupts GRUB's own memory when its font is
+ **Inter 16**, the proportional font the theme used for `terminal-font`. Without the theme's fonts,
+ with Inter 14 alone, at 800×600 or 1024×768, or with GRUB's Unifont as the terminal font, the
+ same 640×480 boot works.
+
+**Fix (0.8.1).** The theme's `terminal-font` is GRUB's fixed-width "GNU Unifont Regular 16"
+(the command line, the entry editor and boot messages; the menu items keep Inter), and on BIOS
+`grub.cfg` asks for `1024x768x32,800x600x32,auto` so the theme's layout fits (the crown no longer
+starts above the top edge). UEFI keeps `gfxmode=auto` (GOP, native mode). The theme
+(`tools/iso/grub/lordos/theme.txt`) is also the installed system's, so installed systems get the
+fix through the `lordos` package; their `/etc/default/grub` keeps `GRUB_GFXMODE=auto`, which is
+now safe at 640×480.
+
+**No KMS display.** LordOS draws through kernel modesetting. QEMU's VMware-compatible display is
+refused by `vmwgfx` ("unsupported hypervisor", "no pitchlock"), and Debian's kernel has no
+`simpledrm`, so there is no `/dev/dri/card0` with any firmware: the boot ended on a black screen.
+Since 0.8.1 `vmwgfx` loads only on VMware itself (`/etc/modprobe.d/lordos-vmwgfx.conf`, DMI vendor
+check), so the firmware framebuffer stays, and lord-sessiond writes on the text console that no
+display device with KMS was found and which display to choose instead. On VMware itself `vmwgfx`
+works (the user's VMware machine reaches the desktop with UEFI and, since 0.8.1, BIOS).
+
+**VMware guests** get `open-vm-tools` (shutdown and restart from the hypervisor, time sync, the
+guest's IP); its units have `ConditionVirtualization=vmware` and stay inactive elsewhere
+(checked on Proxmox: "unmet condition"). Shared clipboard and automatic resize need the desktop
+part (`open-vm-tools-desktop`, X11) and are not supported yet. GPU or CPU composition on VMware:
+see `GPU.md`.
+
+Tested with the rebuilt ISO on VM 123 (Proxmox, q35, 4 vCPUs, emulated HD Audio):
+
+| Firmware | Display | RAM | Result |
+|---|---|---|---|
+| SeaBIOS | VMware compatible | 2 GB | menu at 1024×768 ([screenshot](boot/bios-menu-1024.png)), the timeout boots the kernel (0.8.0: GRUB hung at the menu); no KMS device, so the text console explains it ([screenshot](boot/bios-no-kms-notice.png)) |
+| SeaBIOS | standard VGA | 2 GB | menu, splash, desktop ([screenshot](boot/bios-std-2g-desktop.png)); 1.6 GB available after login; `open-vm-tools` inactive (unmet condition); sink ERR 0 with audio playing from ~1 to ~5 minutes after login and 2 CPU burners |
+| SeaBIOS | standard VGA | 4 GB | desktop |
+| SeaBIOS | standard VGA | 2 GB | "safe mode: no GPU" entry: desktop |
+| OVMF (UEFI) | VirtIO GPU | 2 GB | menu at the native 1280×800 with the theme, splash with its bar, desktop: as in 0.8.0 |
+| VMware Fusion, BIOS | SVGA | 2 GB | 0.8.0: triple fault; 0.8.1: not re-tested on VMware here (the same GRUB code path as the QEMU case) |
+| VMware Fusion, UEFI | SVGA | 4 GB | 0.8.0 already boots to the desktop and the installer (the user's machine) |
+
+Not tested: installing to disk on a BIOS machine with this ISO (no free test disk; the installer
+writes both BIOS and UEFI GRUB, as tested on VM 117 in 0.7.0).
+
## Boot splash and boot menu
From power-on to the login screen LordOS shows its own look: the boot menu, then the crown with a
diff --git a/docs/SOUND.md b/docs/SOUND.md
index a051262..c582c79 100644
--- a/docs/SOUND.md
+++ b/docs/SOUND.md
@@ -220,6 +220,51 @@ lord-server doesn't need real time and doesn't hold PipeWire back:
There was no need to change `pipewire-pulse`'s quantum.
+## Virtual machines (0.8.1)
+
+**Symptom (0.8.0).** On VMware (2 vCPUs, the default emulated card and later HD Audio), YouTube
+in Chromium stuttered: `pw-top` showed ERR on the ALSA sink climbing (600 → 1600) while BUSY was
+~10–30 µs, so the guest CPU wasn't the problem: the emulated card is fed by the host's timers and
+on a busy host they arrive late. It was worst in the first minutes after login.
+
+**What was already there.** PipeWire and WirePlumber detect a VM themselves (`cpu.vm.name`, from
+DMI/CPUID; `pw-cli info 0` shows it, `qemu` on Proxmox). Then PipeWire raises the minimum quantum
+to 1024 (`pipewire.conf`, `vm.overrides`) and Debian's WirePlumber gives emulated PCI cards
+1024-frame periods and 2048 frames of headroom (`/usr/share/wireplumber/wireplumber.conf.d/alsa-vm.conf`).
+On the user's VMware machine those were active and the sink still ran dry (ERR 989 → 1042 in
+~10 s with YouTube playing).
+
+**Fix.** `/etc/wireplumber/wireplumber.conf.d/lordos-vm-audio.conf` (in the `lordos` package,
+`tools/iso/rootfs/`) adds a rule for `alsa_output.*` with the same VM-only match as
+`alsa-vm.conf` (`cpu.vm.name = "~.*"`): 8 periods of 1024 frames, `api.alsa.headroom = 8192`
+(~170 ms at 48 kHz) and `api.alsa.disable-tsched = true` (the card's interrupts drive PipeWire,
+not timers). Its name sorts after `alsa-vm.conf`, so its values win. On the VMware machine it
+took ERR from climbing to 0 → 0 over 30 s of YouTube (sink WAIT 287 µs, BUSY 28 µs). On real
+hardware `cpu.vm.name` is not set, the rule doesn't match and latency stays as before. No unit or
+generator is needed: the match is WirePlumber's own.
+
+Startup: helpers that do background work right after login now yield. `lord-maild` (its first
+full sync starts at login) runs at nice 19 with the idle I/O class; the `lord-media` thumbnail and
+probe worker runs at nice 10 with the lowest best-effort I/O level. The backup thread already ran
+at nice 19, idle I/O, 5 minutes after login and never on battery. PipeWire itself runs with
+real-time priority (see above), so contention inside the guest can't starve it; what the extra
+headroom covers is the host.
+
+The input level meter in Settings → Sound used pavucontrol's 25 Hz `PEAK_DETECT` stream, which in
+PipeWire is a node at rate 25 with a quantum of 1; on the VMware machine PipeWire was seen at
+~36 % CPU while the page was open. It is now a plain 48 kHz mono stream read in blocks of 2048
+samples (~23 levels a second), opened only while the Sound page is open and closed when it
+closes (`apps/settings/Sound.jsx`, `snd_meter` in `server/src/sound/snd.c`). The Voice Recorder computes its level from
+its own recording stream and has no extra one.
+
+**Tested (VM 123, Proxmox, live ISO, emulated HD Audio with `driver=none`, SeaBIOS):** the sink
+shows the rule's values (`wpctl inspect @DEFAULT_AUDIO_SINK@`: `api.alsa.headroom = "8192"`,
+`api.alsa.disable-tsched = "true"`; `/proc/asound/card1/pcm0p/sub0/hw_params`: period 1024,
+buffer 8192), the source keeps Debian's 2048. 30 s of playback with 4 CPU burners in the guest:
+ERR 0 → 0, with and without the rule: KVM's emulated card doesn't show VMware's dropouts, so the
+fix itself was measured on the user's VMware machine, and Proxmox only checks that it applies and
+does no harm.
+
## Pending
- **Real speakers.** The VM now has an HDA card with a codec (`audio0: ich9-intel-hda`; the user
diff --git a/docs/boot/bios-menu-1024.png b/docs/boot/bios-menu-1024.png
new file mode 100644
index 0000000..bf12a82
Binary files /dev/null and b/docs/boot/bios-menu-1024.png differ
diff --git a/docs/boot/bios-no-kms-notice.png b/docs/boot/bios-no-kms-notice.png
new file mode 100644
index 0000000..2daa82b
Binary files /dev/null and b/docs/boot/bios-no-kms-notice.png differ
diff --git a/docs/boot/bios-std-2g-desktop.png b/docs/boot/bios-std-2g-desktop.png
new file mode 100644
index 0000000..831b8c2
Binary files /dev/null and b/docs/boot/bios-std-2g-desktop.png differ