From aa02a45f93f502bdf594483996f5c4bd48c925e9 Mon Sep 17 00:00:00 2001 From: Asahi Lina Date: Dec 29 2024 11:59:32 +0000 Subject: x86-support.adoc: Update for muvm/fex changes. Also use x86-64 instead of x86_64 for consistency and fix a few other nits. --- diff --git a/modules/ROOT/pages/faq.adoc b/modules/ROOT/pages/faq.adoc index 6a9886c..96f1c92 100644 --- a/modules/ROOT/pages/faq.adoc +++ b/modules/ROOT/pages/faq.adoc @@ -61,7 +61,7 @@ In the future, we expect to have a supported process for external-storage instal === Can I run software built for x86-64 (Intel/AMD)? [[x86]] -{variant-name} now includes support for emulating x86 and x86-64 software, initially targeted at gaming. For more details, please see xref:x86-support.adoc[Running x86/x86-64 applications on {variant-name}]. +{variant-name} now includes support for emulating x86 and x86-64 software. For more details, please see xref:x86-support.adoc[Running x86/x86-64 applications on {variant-name}]. For Free/Open Source Software, it is always preferable to make a build for aarch64 (ARM64) instead of trying to emulate an x86-64 build. If your favorite software package is not yet available for this architecture, please request it from its developers! Users comfortable with building software may want to try building it themselves. If you do so, consider xref:package-maintainers::Joining_the_Package_Maintainers.adoc[becoming a package maintainer] to help bring the software to all Fedora users. diff --git a/modules/ROOT/pages/x86-support.adoc b/modules/ROOT/pages/x86-support.adoc index d5d3c1a..3ae2b11 100644 --- a/modules/ROOT/pages/x86-support.adoc +++ b/modules/ROOT/pages/x86-support.adoc @@ -1,17 +1,15 @@ = Running x86/x86-64 applications on {variant-name} -There are lots of lots of legacy x86/x86_64 applications that users want to run on arm64 platforms, including Windows applications and games. To support this in {variant-name}, we have integrated a stack of existing and bespoke components to make it possible to transparently run x86/x86_64 apps directly on arm64 Linux. +There are lots of lots of legacy x86/x86-64 applications that users want to run on arm64 platforms, including Windows applications and games. To support this in {variant-name}, we have integrated a stack of existing and bespoke components to make it possible to transparently run x86/x86-64 apps directly on arm64 Linux. -Since Apple platforms use a 16K page size natively and x86/x86_64 processors use a 4K page size, this is especially tricky, as x86/x86_64 applications generally do not work when presented with a host kernel that requires 16K page alignment. To bridge this gap, we are using a microVM to run an entirely separate guest Linux kernel in 4K page size mode. To keep it as seamless as possible, the guest environment is designed to be as close as possible to the host environment, and we use native context GPU passthrough to have high-performance graphics inside the guest. +Since Apple platforms use a 16K page size natively and x86/x86-64 processors use a 4K page size, this is especially tricky, as x86/x86-64 applications generally do not work when presented with a host kernel that requires 16K page alignment. To bridge this gap, we are using a microVM to run an entirely separate guest Linux kernel in 4K page size mode. To keep it as seamless as possible, the guest environment is designed to be as close as possible to the host environment, and we use native context GPU passthrough to have high-performance graphics inside the guest. The stack consists of these components: -- https://github.com/AsahiLinux/muvm[muvm] (package: `muvm`), our bespoke microVM runner based on https://github.com/containers/libkrun[libkrun]. -- https://fex-emu.com[FEX-emu] (package: `fex-emu`), a fast userspace x86/x86_64 emulator focused on correctness. -- The https://src.fedoraproject.org/rpms/fex-emu-rootfs-fedora[Fedora FEX RootFS] (package: `fex-emu-rootfs-fedora`), which provides common x86/x86_64 library dependencies to be used by emulated applications. -- https://gitlab.freedesktop.org/asahi/mesa[mesa] (packages: `mesa-fex-emu-overlay-i386` and `mesa-fex-emu-overlay-x86_64`), built for the x86/x86_64 architectures and packaged as a FEX RootFS overlay. This provides the OpenGL/OpenCL/Vulkan support for Apple GPUs. -- https://chromium.googlesource.com/chromiumos/platform2/+/HEAD/vm_tools/sommelier/README.md[sommelier] (package: `sommelier`), a forwarding Wayland compositor for cross-domain window passthrough (will likely be replaced with a native X11 passthrough solution in the future). -- https://github.com/WhatAmISupposedToPutHere/hidpipe[hidpipe] (package: `hidpipe`), a proxy for HID input devices to allow gamepads to work within the VM. +- https://github.com/AsahiLinux/muvm[muvm] (package: `muvm`), our bespoke microVM runner based on https://github.com/containers/libkrun[libkrun]. This also includes components for X11 forwarding and HID input device proxying. +- https://fex-emu.com[FEX-emu] (package: `fex-emu`), a fast userspace x86/x86-64 emulator focused on correctness. +- The https://src.fedoraproject.org/rpms/fex-emu-rootfs-fedora[Fedora FEX RootFS] (package: `fex-emu-rootfs-fedora`), which provides common x86/x86-64 library dependencies to be used by emulated applications. +- https://gitlab.freedesktop.org/asahi/mesa[mesa] (packages: `mesa-fex-emu-overlay-i386` and `mesa-fex-emu-overlay-x86-64`), built for the x86/x86-64 architectures and packaged as a FEX RootFS overlay. This provides the OpenGL/OpenCL/Vulkan support for Apple GPUs. We also have our own https://pagure.io/fedora-asahi/steam[Steam wrapper] that automates the process of installing and launching Steam inside the microVM stack. When running Windows games using Steam, these open-source components are used behind the scenes: @@ -19,30 +17,48 @@ We also have our own https://pagure.io/fedora-asahi/steam[Steam wrapper] that au - https://github.com/doitsujin/dxvk[dxvk], a translation layer that converts the Windows DirectX 8 - DirectX 11 APIs to Vulkan. - https://github.com/HansKristian-Work/vkd3d-proton[vkd3d-proton], a translation layer that converts the Windows DirectX 12 API to Vulkan. -This technology stack is currently primarily aimed at running x86 and x86-64 games, although in the future it should also be useful to run non-game productivity applications. When possible, you should prefer native alternatives over emulation. Please read xref:faq.adoc#x86[this FAQ entry] for more information. +== Scope + +This technology stack is primarily aimed at running x86 and x86-64 games, but it can also be used to run non-game productivity applications. When possible, you should prefer native alternatives over emulation. Please read xref:faq.adoc#x86[this FAQ entry] for more information. + +The scope of this solution is limited to _portable x86 and x86-64 applications_ that are intended to be run from your home directory (or, at most, manually unpacked into `/opt` by the user), including AppImages. It is _not_ intended to run x86-64 applications that must be installed as system packages, which are built for a specific Linux distribution or require installation of complex system dependencies, or which require running dedicated installers as root. + +In particular, the x86-64 environment is _not_ a self-contained root filesystem, but rather a minimal, immutable overlay on top of your existing arm64 root filesystem. That means that you cannot make changes to it, install additional packages, etc. There is no root access available at all within the x86-64 environment. == Usage +=== Steam + Just use `dnf install steam` to install our Steam wrapper, and then run Steam from your desktop's launcher (or the `steam` command) to download and install Steam. This will install all necessary dependencies automatically. -To run applications within a microVM manually, just prefix the command with `muvm --`. For example, `muvm \-- sh` will give you a shell within the microVM environment. In this environment, the kernel's binfmt support is already configured to use FEX to run x86/x86_64 applications, so you should be able to just run them. Note that we do not officially support applications outside of Steam right now, as there are a number of issues that can make the experience quite frustrating. This will change in the future. +=== Other applications + +To install the emulation stack by itself, use `dnf install fex-emu`. This will pull in the required dependencies automatically. + +You cannot run x86-64 applications directly from the host (yet), as they must be launched from the microVM. To do so, run `muvm +++--+++ /path/to/executable`. You must use an absolute path, as `muvm` does not currently preserve the current working directory. In this environment, the kernel's binfmt support is already configured to use FEX to run x86/x86-64 applications, so you should be able to just run them. + +If your application uses a launcher shell script instead of directly running its main binary, you should run it through `FEXBash`. For example, use `muvm +++--+++ FEXBash /path/to/launcher.sh`. Doing so ensures that the shell runs in the emulated environment and a few critical shell commands behave as they would for x86-64 applications, which makes it more likely that the shell script will work as intended. + +You can also use `muvm +++--+++ bash` to launch an arm64 shell within the 4K MicroVM, or `muvm +++--+++ FEXBash` to launch an x86-64 shell. The x86-64 shell will behave similarly to the arm64 shell and most commands will run as arm64 binaries, but a few (such as `ls`) will run under emulation, which lets you "see" the world as x86-64 apps do. == How it works `muvm` creates a virtual machine that shares as much with the host OS as possible. Within the VM, the root filesystem is _the same as the host root filesystem_, with the following exceptions: -* `/dev`, `/sys`, and `/proc` are guest-private. +* `/dev`, `/sys`, and `/proc` are guest-private, except for `/dev/shm` which is shared with the host, allowing host apps and guest apps to coherently share memory. * `/run` is also private to the guest * The FEX-emu rootfs and overlay images are mounted under `/run/fex-emu/`, with the combined overlay rootfs available at `/run/fex-emu/rootfs`. * `/usr/share/fex-emu` and `/usr/local/share/fex-emu` are overmounted with a tmpfs to inject a FEX `Config.json` suitable for use within the VM * A tmpfs is also mounted on `/tmp/.X11-unix`, so X11 server sockets are private to the VM -* The entire host filesystem view is available at `/run/muvm-host`, including any overlaid mounts. For example, you can access the host's `/run` at `/run/muvm-host/run`. (Note: /run/muvm-host/dev exists but will not do what you might hope it does. Host devices are not available in the guest.) +* The entire host filesystem view is available at `/run/muvm-host`, including any overlaid mounts. For example, you can access the host's `/run` at `/run/muvm-host/run`. (Note: `/run/muvm-host/dev` exists but will not do what you might hope it does. Host devices are not available in the guest.) -This means that `/usr`, `/home`, `/etc`, `/opt`, `/var`, `/tmp`, and any other directories in your filesystem root are _shared between the guest and the host_. The arm64 guest OS does not run its own root filesystem, but rather _runs exactly the same binaries as your host OS does_. +This means that `/usr`, `/home`, `/etc`, `/opt`, `/var`, `/tmp`, and any other directories in your filesystem root are _shared between the guest and the host_. The aarch64 guest OS does not run its own root filesystem, but rather _runs exactly the same binaries as your host OS does_. -Additionally, FEX itself uses the filesystem mounted at `/run/fex-emu/rootfs` as its virtual RootFS. This means that x86/x86_64 applications (and only those) will see the contents of that directory overlaid on top of the root filesystem. This is how we make x86/x86_64 libraries available to those applications, while still sharing most of the filesystem contents. +Additionally, FEX itself uses the filesystem mounted at `/run/fex-emu/rootfs` as its virtual RootFS. This means that x86/x86-64 applications (and only those) will see the contents of that directory overlaid on top of the root filesystem. This is how we make x86/x86-64 libraries available to those applications, while still sharing most of the filesystem contents. -When muvm starts, it registers FEX as a binfmt provider, so x86/x86_64 applications will be transparently run through it. On startup, FEX will detect that TSO support is available on the Apple Silicon platform (even within the VM), and automatically enable it for faster accurate emulation. +When muvm starts, it registers FEX as a binfmt provider, so x86/x86-64 applications will be transparently run through it. On startup, FEX will detect that TSO support is available on the Apple Silicon platform (even within the VM), and automatically enable it for faster accurate emulation. + +TIP: Mountpoints in the host are propagated to the guest _when they are first accessed_, automagically. This allows guest apps to distinguish different filesystems, which keeps device/inode semantics correct. If you have a partition mounted on the host at `/mnt/steam` and you run `mount` within the guest, you won't see it at first. If you run `ls /mnt/steam` and then run `mount` again, the mount will have magically been added to the mount list. This is normal and working as intended! == Known issues @@ -52,19 +68,17 @@ As this project is still in its early stages, we aimed for correctness for the i For Windows DX8-DX11 games under Proton in particular, you might want to try WineD3D instead of DXVK. WineD3D uses OpenGL instead of Vulkan as its backend, and it _may_ have better performance thanks to optimizations in our OpenGL driver that are not available on Vulkan. To enable it, change the Steam launch options to `PROTON_USE_WINED3D=1 %command%`. Note that DXVK tends to have better compatibility, so this is a trade-off. Let us know what games work better using either backend! -=== Window management is weird (titlebar problems, popup problems, DPI problems, etc.) - -These are known issues caused by bugs/limitations in Sommelier. We recommend using our x86/x86_64 stack only to run fullscreen applications (games, Steam in Big Picture mode) at this time. We're working on a solution to this issue by replacing Sommelier with a more lightweight alternative. - -If you need to access the regular Steam client, you can exit from Big Picture using Alt-F4. The menus may not work properly at this time. If you need to access Steam Settings, you can do so by clicking the Library tab, then clicking on the gear icon. +Older 32-bit games may run very slowly if they make heavy use of the 80-bit x87 floating-point unit, since these operations have to be emulated in software for full compatibility (the same issue exists in Rosetta on macOS). You can run these games with hardware-based 64-bit floating-point emulation, which is less accurate but much faster. To do so, change the Steam launch options to `FEX_X87REDUCEDPRECISION=1 %command%`. This mode can cause subtle issues in some games due to the reduced accuracy, but most games should run fine (and much faster). === The VM uses a lot of RAM -To allow guest apps to use a large amount of RAM (as some modern games require), by default `muvm` allows the guest to use up to 80% of the system RAM. This also means that some of that will be taken up by guest page cache. Especially on lower RAM size machines (16GB or lower), we recommend not running any heavy host applications while the VM is in use. We don't recommend gaming on 8GB machines. +To allow guest apps to use a large amount of RAM (as some modern games require), by default `muvm` allows the guest to use up to 80% of the system RAM. This also means that some of that will be taken up by guest page cache, appearing to the host as if the VM is taking up most of system RAM. `muvm` has the ability to reduce guest page cache usage as host memory pressure increases, so if you increase host memory usage, the VM should reduce its usage accordingly (as long as it is able to discard unused cache RAM). + +On lower RAM size machines (16GB or lower), we recommend not running any heavy host applications while the VM is in use. We don't recommend running complex games on 8GB machines. -You can configure the guest RAM allocation with the `muvm --mem=SIZE` parameter. +To inspect VM memory usage while it is running, use `muvm -ti +++--+++ free`. You can also run `muvm -ti +++--+++ htop` (if you have `htop` installed) to get more detailed information, or substitute your system information tool of choice. -This will be less of an issue in the future, when we enable virtiofs-DAX in `muvm`. This directly maps host filesystem cache pages into the guest, and therefore relieves memory pressure. +If you wish to limit the maximum memory usage of the MicroVM, you can configure the guest RAM allocation with the `muvm --mem=SIZE` parameter. === I can't access media mounted under `/run/media` within the VM @@ -76,16 +90,50 @@ This does not work (not even via `/run/muvm-host/run/media`) due to missing POSI This is as close to Rosetta as we can get! The main difference is that Rosetta side-steps the page size issue by instead relying on the XNU kernel's multiple page size support for user processes, so it doesn't need a VM. While making Linux support mixed page sizes would not be completely impossible in theory, it would be an enormous project that would likely take years to complete, and it isn't at all clear whether such a change would be accepted upstream (Linux doesn't even have boot-time page size selection within a single kernel yet!). -Other than the page size issue, FEX and Rosetta are comparable technologies (both are emulators, despite what Apple marketing might have you believe). Both FEX and Rosetta use the unique Apple Silicon CPU feature that is most important for x86/x86_64 emulation performance: TSO mode. Thanks to this feature, FEX can offer fast _and_ accurate x86/x86_64 emulation on Apple Silicon systems. +Other than the page size issue, FEX and Rosetta are comparable technologies (both are emulators, despite what Apple marketing might have you believe). Both FEX and Rosetta use the unique Apple Silicon CPU feature that is most important for x86/x86-64 emulation performance: TSO mode. Thanks to this feature, FEX can offer fast _and_ accurate x86/x86-64 emulation on Apple Silicon systems. === Why not just use a 4K host kernel? -While Apple Silicon systems support 4K CPU pages, the rest of the hardware (IOMMUs, GPU) runs with 16K pages only. The Linux kernel does not play nicely in this environment, as it generally assumes that the CPU page size is at least as large or larger than the IOMMU page size. In the past we had some kernel patches to make this partially work, but they were buggy and incomplete, so we abandoned the approach. Even if it did work well, running the whole system using 4K pages has a measurable performance impact, so we would never ship 4K kernels by default. Therefore, running x86/x86_64 would require that users manually change their kernel and reboot, which is quite cumbersome. +While Apple Silicon systems support 4K CPU pages, the rest of the hardware (IOMMUs, GPU) runs with 16K pages only. The Linux kernel does not play nicely in this environment, as it generally assumes that the CPU page size is at least as large or larger than the IOMMU page size. In the past we had some kernel patches to make this partially work, but they were buggy and incomplete, so we abandoned the approach. Even if it did work well, running the whole system using 4K pages has a measurable performance impact, so we would never ship 4K kernels by default. Therefore, running x86/x86-64 apps would require that users manually change their kernel and reboot, which is quite cumbersome. === Why not box64? box64 and FEX-Emu have different approaches to emulation, with FEX-Emu aiming for better correctness by default (but requiring a more complex setup) while box64 aims to cover more "out of the box" use cases (like running a subset of applications directly on a 16K kernel without a VM using some tricks). We have chosen FEX-Emu for our stack because we believe it will have higher compatibility with its approach, but both have their uses. box64 is https://src.fedoraproject.org/rpms/box64[packaged in Fedora], so we encourage users to try it (both natively and within muvm) and let us know how it compares! +=== My x86-64 or x86 application is missing some system libraries, what do I do? + +Our immutable RootFS contains a large set of common x86-64 and x86 libraries that are commonly used as dependencies, but we cannot ship every possible library. You can view the package list https://pagure.io/fedora-kiwi-descriptions/blob/rawhide/f/teams/asahi.xml[here]. + +If the missing library is a relatively simple, common library with no or very simple dependencies, and which would not add much size to our RootFS images, please submit a PR to the repo linked above so we can include it in future releases of the RootFS. Make sure to note what application requires the library, and why you think we should include it. + +If your app requires a complicated framework (such as Qt) or an uncommon, niche library, then the application is not built as a "portable" application and not expected to work out-of-the-box on most systems. To work around the issue, you can manually download the missing libraries, extract them into your home directory, and use `LD_LIBRARY_PATH` to make your application find them. You can use the following command to download x86-64 RPMs from your arm64 Fedora installation: + +``` +dnf download --repo=fedora --repo=updates --forcearch=x86_64 --best [package1] [package2]... +``` + +You can then use `rpmdev-extract` to extract the contents of the RPM, and then configure `LD_LIBRARY_PATH` as appropriate. + +It is also possible to overlay RPMs into the existing RootFS, though this should be considered advanced functionality. Once you have an RPM, you can convert it to an erofs image using these commands: + +``` +rpm2archive -n mypackage.rpm +mkfs.erofs --tar=f mypackage.rpm.erofs mypackage.rpm.tar +``` + +Then, you can manually launch `muvm` with the base erofs images and your custom erofs image on top, like this: + +``` +muvm \ + -f /usr/share/fex-emu/RootFS/default.erofs \ + -f /usr/share/fex-emu/overlays/mesa-x86_64.erofs \ + -f /usr/share/fex-emu/overlays/mesa-i386.erofs \ + -f mypackage.rpm.erofs \ + +``` + +This will overlay the add-on package onto the RootFS used for FEX. Please keep in mind that this may or may not work as intended, and it should not be considered a supported solution. + === Steam says steamwebhelper crashed, what do I do? Just let it restart, and it should work on the second try. Steam has a timeout for steamwebhelper, and when running under emulation, startup is slow enough that the timeout expires. This usually only happens on a cold startup. @@ -100,22 +148,17 @@ This is caused by the "Disable while typing" touchpad feature. You can turn it o === Can I run Windows applications outside of Steam? -At this point, we do not support running Windows apps outside of Steam for two reasons: - -- Non-Proton Wine does not yet work on Fedora + FEX due to https://github.com/FEX-Emu/FEX/pull/3831[FEX issues] that we are working on. -- Sommelier (the cross-vm compositor that we use currently) is https://github.com/AsahiLinux/muvm/issues/73[quite buggy] and not really suitable for non-fullscreen applications. We are working on a new solution that directly proxies the X11 protocol cross-domain to the host XWayland/compositor, which fixes all of these problems and makes the applications act as native X11 apps running on the host OS. +At this point, we do not support running Windows apps outside of Steam as non-proton Wine not yet work on Fedora. We are working on resolving the underlying https://github.com/FEX-Emu/FEX/pull/4225[FEX issue], so we expect to support this relatively soon. -Once these issues are resolved, you will be able to use wine under muvm to run Windows apps. +In the meantime, you can use Steam's Proton to run non-Steam Windows applications directly from Steam. -=== Can I run x86_64/x86 Linux applications? +=== Can I run x86-64/x86 Linux applications? Native Linux games should generally work under muvm, as long as they are self-contained and do not depend on complex host system libraries (we ship a large selection of common dependencies, but not everything under the sun). -Non-game productivity apps may work, but window management will probably be quite broken due to Sommelier bugs (see the previous answer). - === Is Wayland supported? -Wayland is not supported inside the VM at this time (Sommelier is a Wayland compositor, but it is used in an XWayland-exclusive mode). As most of the legacy x86/x86_64 applications people want to run are X11 applications, we are focusing on X11 support first. This means that you cannot run native Wayland apps inside the VM at this time. Of course, the host desktop is still a Wayland desktop, and X11 support is provided by XWayland. +Wayland is not supported inside the VM at this time. As most of the legacy x86/x86-64 applications people want to run are X11 applications, we are focusing on X11 support first. This means that you cannot run native Wayland apps inside the VM at this time. Of course, the host desktop is still a Wayland desktop, and X11 support is provided by XWayland. === Can I access hardware from applications running within the microVM? @@ -125,22 +168,42 @@ As the VM does not pass through any host hardware other than the GPU and the vir - Gamepads via hid/uinput passthrough - Sound I/O via the PulseAudio socket protocol footnote:[This works with PipeWire running on the host with pipewire-pulse, as installed by default. You do *not* need to and should not install PulseAudio proper, as that will break your speaker support!] +We are researching the possibility of passing through PipeWire, which will allow webcams to be used within the VM. + +=== Can I use input methods (IMEs) in applications within the microVM? + +You can use the classic _xim_ input method system used in X11. muvm should already configure the environment variables appropriately to make this work for Qt and GTK applications (loading the "xim" plugin), as long as the input method framework you are using on your host system supports it. We have tested this with _fcitx5_ and Steam running on KDE Plasma. + +In the future, once Wayland passthrough is supported, the native Wayland input protocol mechanism should work with any host input method framework (through a plugin usually called "wayland"). There are no plans to support non-window-system-based input methods (such as the direct "ibus" and "fcitx" plugins), since they would require us to ship x86-64 shared libraries for all possible input methods in the immutable virtual x86-64 system, and would also require proxying of their bespoke protocols, which is infeasible. + === Is this like a Qemu/libvirt/UTM/Parallels/VMWare/VirtualBox/etc. VM? No, muvm does not work like a traditional whole-system VM. While it does also use KVM as a backend for efficient virtualization, the concept is very different to traditional VMs running entirely separate guest operating systems. The guest kernel is a https://github.com/containers/libkrunfw[special kernel] optimized to start up in a fraction of a second, and the VM monitor passes through the host filesystem mostly as-is. There is no low-level hardware passthrough (USB, etc.) and instead we focus on higher-level software protocol passthrough, like X11/Wayland. The VM does not run its own standalone init system, only some minimal startup code. This means that the environment within the VM should "feel" the same as the host OS from the point of view of applications, just with a 4K page size instead of a 16K page size. +=== Do browsers work within the VM guest? + +Yes, but they will run in X11 mode. However, there is one caveat: *browser instances within the guest cannot communicate with browser instances outside the guest, and it is dangerous to run the same browser profile in both the guest and the host*. + +To avoid these problems, muvm configures an environment variable to force Firefox to use a dedicated profile when launched within the VM. This means that applications that launch a browser (such as for login or documentation purposes) will work as intended, but Firefox will launch using a dedicated profile without access to your cookies, history, etc. + +CAUTION: If you launch the same browser profile in the guest and the host simultaneously, your profile data may become corrupted. If your default browser is not Firefox, and you are using emulated apps that might launch your default browser inadvertently, we strongly recommend closing all browser windows before using muvm or manually configuring separate profiles. + === Can I sudo inside the VM? Since the VM monitor runs as your own user identity, it cannot gain root privileges. "root" inside the VM still only has the privileges of your own user, so sudo doesn't make much sense (and in fact doesn't work). We recommend installing software that you want to use with muvm+FEX under your home directory. For software that is designed to be installed under /opt or similar, we recommend performing the installation steps manually on the host OS, and then just running the app under muvm. +If you need access to a root shell within the VM for debugging purposes, you can run `muvm -tip 3335 +++--+++ bash`. Keep in mind that, despite being "root", you will not be able to modify most system files owned by root, and any files you create will actually be owned by your non-root user identity. A root shell is mainly useful to do things like `strace` other processes or change guest kernel or network configuration settings (but these changes will not persist across a VM restart). + === Can applications within the VM communicate with applications outside the VM? Communication is mostly limited to the host filesystem. The VM shares your home directory (and in fact most of the filesystem) with the host, so any files you create on one side will be visible on the other. -In the future, we will enable virtiofs-DAX, which will allow for shared memory communication (/dev/shm) between guest apps and host apps, but this isn't quite ready yet. +Thanks to virtiofs-DAX, shared memory communication (`/dev/shm`) is also available between guest apps and host apps. This is used, for example, by the X11 forwarding code. It is also possible to share audio between host and guest apps by using the PulseAudio forwarding support. For example, you can record guest audio by using a recording app on the host and recording from the system "Monitor" device. You can also configure virtual sinks/sources in the host using the normal PipeWire mechanisms, and direct guest apps to use those for audio I/O to have custom audio routing and processing. Note that the native PipeWire protocol is not passed through, only the PulseAudio protocol which is more limited (but more commonly used by applications). ALSA applications are supported via the `pulse` plug-in. +If you are using a host compositor that supports XWayland video bridging (such as KDE Plasma / KWin), you will be able to screen share / screen capture from the VM, including full host screens and Wayland windows. Make sure the app you are running supports "classic" XComposite window/screen capture. When you initiate screen sharing, you will be able to directly select X11 application windows, or choose the virtual "Xwayland Video Bridge" window. When you do so, KDE will automatically prompt you for the actual window or screen you wish to share. + === Why do I have fewer CPU cores inside the VM? By default, `muvm` passes through as many CPUs as there are performance cores on your host machine, and pins those vCPUs to the physical performance cores. Since the host CPU scheduler has no visibility into the guest CPU scheduler, this ensures that performance is consistent. You can modify this behavior with the `muvm --cpu-list=CPU_LIST` option. @@ -161,21 +224,15 @@ NOTE: The default mountpoint for drives mounted via the desktop environment (udi . Ensure that the filesystem root is accessible to your regular user: + -`sudo chown ${USER}: /mnt/steam` +`sudo chown $\{USER}: /mnt/steam` . Create an empty folder named `steamapps` at the root of the mount: + `mkdir /mnt/steam/steamapps` . Start up Steam normally -+ -NOTE: Steam will start up in Big Picture mode - -. Exit Big Picture mode by pressing Alt+F4 . Click on the Library tab, then click the gear (settings) icon -+ -TIP: The settings window may pop up with the wrong size. Click and drag the resize handle on the bottom right to snap to the proper size. . Select *Storage* on the left menu, click on the combo box at the top of the panel, and select *Add Drive*.