Home / Docs / Deployment & Architecture
MayteraOS Deploy Architecture: Running Under Virtualization
MayteraOS is developed and tested primarily inside QEMU/KVM virtual machines. This page describes the virtual-hardware configuration that is known to run the full desktop with zero regressions, the design rationale behind it, and the roadmap items it exposes.
Verified virtual machine configuration
The current build produces a single disk image with a GPT partition table holding exactly two partitions, not two separate disks: the build's own gate refuses to produce an image with any other partition count, specifically to prevent a past regression where the layout silently collapsed back to one bare FAT partition. The table below reflects that single-image layout.
| Setting | Value | Why |
|---|---|---|
| CPU model | Generic baseline (e.g. QEMU's kvm64) | Host CPU passthrough on a modern Xeon (Gold 6248 class) crashed the compositor with an AVX/CPUID-related page fault; a generic CPU model without the newest vector extensions avoids the crash. Fixing AVX feature handling is a roadmap item. |
| Cores | 8 (1-16 verified) | The desktop boots fully and runs stably at 1, 2, 4, 8, and 16 cores. |
| Memory | 4096 MB | 2048 MB was too tight for the ext2 root, desktop widgets, and compositor together; 4 GB boots clean. |
| Machine type | i440fx ("pc") | The ATA driver expects legacy IDE I/O ports (0x1F0); newer chipset models that provide only AHCI break disk I/O. AHCI support is a roadmap item. |
| Firmware | UEFI (OVMF) with secure boot disabled | The bootloader (BOOTX64.EFI) is unsigned, so secure boot must be off. |
| Disk (single image, GPT, 2 partitions) | Partition 1: FAT32 EFI System Partition. Partition 2: ext2 root filesystem. | Partition 1 holds the bootloader, /boot/kernel.elf, and the boot splash. Partition 2 is the real root: /APPS, /CONFIG, wallpapers, and the userland compositor. One image with a real partition table, rather than two attached disks, is what lets an installer or a dd-to-USB-stick just write one file. |
| Network | e1000 (emulated Intel NIC) | Matches one of the supported NIC drivers (VirtIO-net is tried first, then E1000). |
| Serial | Socket-backed serial console | Used for the kernel's text shell and debug output. |
With this configuration the full desktop comes up: live widgets (weather, stocks, clock, calendar, and a system monitor showing all cores), the desktop pet, and sticky notes, all verified against a live screen (advancing clock, continuous redraw).
The disk is the system
A key design property: an installed MayteraOS system is entirely contained in that one disk image. There is no host-side installation state. Moving the OS to a new machine, physical or virtual, means moving that one image and attaching it as a legacy IDE disk (or writing it to a USB stick). This is how the entire development environment has survived hardware changes in the past: the disk image was restored verbatim onto different server hardware and booted unchanged.
Updating a deployed system
Kernel updates are deployed by writing the newly built kernel.elf onto the FAT32 boot partition; userland apps are written into the ext2 root. Every build embeds an incrementing build number that the desktop displays, which is the standard check that the new kernel actually loaded. The detailed internal deploy procedure is maintained internally.
SMP behavior
The desktop boots fully and stably at any tested core count (1 through 16). The current scheduler design pins user processes, including the compositor, to the bootstrap processor and runs kernel work on the application processors; running user processes on secondary cores is opt-in per process. This sidesteps a known fault path involving per-CPU page-table state during demand paging, at the cost of not yet load-balancing user applications across cores.
One practical note for QEMU users: a guest reset does not re-read the configured core count; QEMU keeps its original SMP topology. Changing the number of cores requires a full stop and start of the VM.
Known constraints and roadmap
- Avoid host-CPU passthrough on machines with the newest vector extensions until the compositor's AVX handling is fixed; use a generic CPU model instead.
- Storage requires legacy IDE emulation today; AHCI/SATA support is planned.
- Multi-core currently parallelizes kernel work only; true per-core scheduling of user applications is a planned deeper change.