// guide

Features

What Visor does, and how each piece behaves.

The graphical menu renders into a full-screen back buffer and presents via GOP — no flicker, ever. Selection changes slide and cross-fade, pages flip with an animation, and the whole screen fades in and out around boot. The selection highlight can be a flat rounded card or a frosted-glass blur. Entries beyond entries_per_page paginate with chevron indicators. A text-mode menu (text_menu=1) covers headless setups and firmware that refuses graphics — Visor falls back to it automatically.

Auto-detection (no boot.conf)

With no config, Visor builds the menu itself. Scan order, across every readable volume:

  1. Windows Boot Manager — \EFI\Microsoft\Boot\bootmgfw.efi and friends.
  2. BLS entries — \loader\entries\*.conf (systemd-boot style), including sort tries/ostree indexes.
  3. UKIs — every *.efi in \EFI\Linux.
  4. Raw kernels — vmlinuz*/bzImage* in \boot, \@\boot, and the volume root, each paired with its initramfs. This scan always runs (a UKI does not hide your plain kernels); it is only skipped when BLS entries already reference the same files.
  5. Distro loaders — \EFI\<distro>\{shimx64,grubx64}.efi, as a last resort.

Automatic kernel cmdline

A detected raw kernel still needs root= to reach userspace, so Visor derives an accurate cmdline at boot, with no sidecar file, from the first available source:

  1. UKI .cmdline section — a UKI in \EFI\Linux embeds the distro's complete cmdline (root UUID, btrfs rootflags=subvol=, crypt flags). Visor parses the PE section table and reuses it.
  2. /etc/fstab — on any volume the firmware can read (e.g. via an EfiFs driver), the / line supplies the exact root spec and btrfs subvolume flags, honoring ro.
  3. GPT root partition type — the Discoverable Partitions root GUID for the build architecture yields root=PARTUUID=… rw, straight from the partition table via BlockIo — no filesystem access at all.

The boot log records which source was used and the exact line derived.

Live USB hotplug

When the menu is armed, Visor first scans all volumes that are already connected (including USB sticks that were plugged in before the menu appeared). It then watches for volumes that appear later and adds their entries live — the new icon fades and scales in while the existing row slides over. Entries are pinned to the stick's partition GUID and volume handle, so files load from the stick that brought them. Unplugging reverses it: the entries leave and the surviving icons slide back together. Replug never duplicates. Hotplugged and pre-connected volumes derive cmdlines only from sources on the stick itself. Disable with hotplug=0. The setting scan_existing=1 forces scanning of pre-connected volumes even when boot.conf has manual entries.

Btrfs snapshots

Press V to open the snapshot panel for the selected Linux entry and boot any snapshot once. Sources, in order:

  1. \EFI\visor\snapshots.conf, generated on the host by tools/visor-snapshot-sync — carries exact per-snapshot cmdlines/kernels, supports multiple OSes. Visor also reads \EFI\visor\snapshot.conf (singular) as a fallback.
  2. Direct btrfs detection (needs the btrfs EfiFs driver): snapper's .snapshots/N/snapshot, Timeshift's timeshift-btrfs/snapshots/<ts>/@, and named subvolumes under .snapshots, snapshots, @snapshots.

The scanner rewrites the entry's rootflags=subvol= to the snapshot subvolume and shows the newest twelve. Visor never makes a snapshot writable or performs a rollback — your initramfs must support the distro's read-only snapshot workflow. snapshots = 0 | manifest | 1 selects the mode.

Accent colors (Material You)

With accent=1, Visor extracts a seed color from the wallpaper — Celebi quantization then scoring, the same pipeline as Android's Material You — and builds a tonal palette used for icons, underline, and text. Variants: tonal, vibrant, expressive, fidelity, content, neutral, monochrome (accent_variant=). The whole HCT/CAM16 color pipeline runs in Q16 fixed-point integer math (firmware has no floating point) and tracks the reference Material You implementation closely — chromatic wallpapers match hue within half a degree.

Immutable distros & OSTree

BLS configs from OSTree-based systems (Fedora Silverblue/Kinoite, etc.) are grouped into one entry per OS with a version panel: V cycles deployments (current, rollback, pinned), so an atomic system shows one clean icon instead of three near-identical entries.

Non-FAT filesystems

UEFI firmware only reads FAT. To auto-detect kernels living on ext4, btrfs, xfs, and friends, Visor loads EfiFs drivers from \EFI\visor\drivers\. The installer (and visor drivers) detects the /boot filesystem and downloads the matching driver — pinned to a fixed EfiFs release and SHA-256 verified. Drivers are deferred: loaded at startup but only started when a file actually needs them or the fast scan finds nothing, keeping the menu at ~1 second even with the btrfs driver installed.

Windows

Windows entries chainload bootmgfw.efi by device path, so BitLocker and the BCD store behave exactly as if the firmware had booted Windows directly. If an entry has no kernel path at all, Visor searches for the Windows Boot Manager across volumes (honoring the uuid= pin).

Editing & recovery

When a LUKS entry (luks=1) is selected, Visor shows a passphrase prompt. F2 toggles showing what you typed (check your keyboard layout). luks_confirm=1 requires typing the passphrase twice — a mismatch reprompts instead of booting. luks_verbose=1 removes quiet splash from the cmdline so the initramfs retry prompt is visible when a passphrase is rejected.