From 7c9c4bc347f00ed4605c02ba21dab88c4bb31879 Mon Sep 17 00:00:00 2001 From: Coopydood <39441479+Coopydood@users.noreply.github.com> Date: Mon, 2 Oct 2023 01:02:57 +0100 Subject: [PATCH] Documentation additions --- docs/FAQs.md | 51 +++++++++++++++++++++++++++- docs/Gotchas.md | 16 +++++++++ docs/RemoteDesktop.md | 79 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 145 insertions(+), 1 deletion(-) create mode 100644 docs/RemoteDesktop.md diff --git a/docs/FAQs.md b/docs/FAQs.md index 6c5b10e..f6ac0a5 100644 --- a/docs/FAQs.md +++ b/docs/FAQs.md @@ -71,6 +71,55 @@ There are also a few automatic system checkers built in, included in the `./scri +
What is a "qcow2" file?
 + +Moof! (Clarus reference, anyone?) + +A ``.qcow2`` file is simply a virtual hard disk file used mainly by QEMU/KVM. + +The VMware equivalent would be a ``.vmdk`` file. + +The VirtualBox equivalent would be a ``.vdi`` or ``.vdk`` file. + +
+ +
What are QEMU arguments?
 + +WHY HAS MY DAD BEEN GONE SO LONG? WORKING WITH QEMU AGAIN?! +NO MICHAEL! HE JUST WENT TO GET THE MILK- + +Oh, sorry, not that kind of QEMU argument! + +The QEMU arguments are simply the list of variables passed on to the ``qemu-system-x86_64`` program, used to set up your virtual machine. + +The arguments themselves shouldn't be edited by the user, as they've been pre-programmed to work out-of-the-box. + +They look similar to this: + +``` +args=( +-global ICH9-LPC.acpi-pci-hotplug-with-bridge-support=off +-enable-kvm -m "$ALLOCATED_RAM" -cpu "$CPU_MODEL",kvm=on,vendor=GenuineIntel,+invtsc,vmware-cpuid-freq=on,"$CPU_FEATURE_ARGS" +-machine q35 +-usb -device usb-kbd -device usb-tablet #USB_DEV +-smp "$CPU_THREADS",cores="$CPU_CORES",sockets="$CPU_SOCKETS" +-device usb-ehci,id=ehci +-device qemu-xhci,id=xhci +-device pcie-root-port,bus=pcie.0,slot=1,x-speed=16,x-width=32 +... +) +``` + +
+ +
What do you mean by "scripts" and "configs"?
 + +When the project mentions "scripts", it means either *the Python files used to run the program*, or *the user-generated shell scripts used to boot a virtual machine.* + +When the project mentions "configs", it's typically referring to *files generated by AutoPilot*, in the form of shell scripts ending in ``.sh``. These were generated based on your specific configuration, hence the naming. + +
+
I'm here for GPU (or any PCI) passthrough!
 Great! The project can assist you with this too. @@ -105,7 +154,7 @@ And finally, the ``internal`` folder. If you see this, run. You shouldn't have i
-
Can I edit the boot script I made with AutoPilot?
 +
Can I edit the boot config I made with AutoPilot?
 Yes, you can. AutoPilot is designed to create a new boot script based on your preferences, but you may desire to change these over time without using AutoPilot again, and it has been designed to allow you to do so. diff --git a/docs/Gotchas.md b/docs/Gotchas.md index 9fd6e97..9f40f4f 100644 --- a/docs/Gotchas.md +++ b/docs/Gotchas.md @@ -12,6 +12,8 @@ Please note this document will be updated frequently. ***
main.py: Permission denied
 +**NOTE:** As of v0.9.8, files are packaged as executable by default, and do not require additional permission modifications. + Awww, you little donkey. You forgot to make it executable. ```sh @@ -104,6 +106,20 @@ Thankfully, this is of course an easy fix. You'll need to run the script as supe ```sh $ sudo ./boot.sh ``` +
+ +
Unknown PCI header type "127" (vendor reset bug)
 + +Sometimes, when stopping or resetting a virtual machine with an AMD GPU passed through, the "reset" mechanism used to detach the GPU from the virtual machine fails. + +This is due to a problem known as the **vendor reset bug**. It affects a large variety of AMD GPUs, and is a firmware-level flaw. + +Unfortunately, after seeing this message, the only way to use the GPU again with a VM (even the same one) is to restart the host entirely. Even this might be difficult, as the shutdown process may hang when trying to reset the GPU before power off. Make sure you save all your work, and allow as many system processes to exit as possible, and then hard-reset the host. + +Although annoying, it's pretty benign. You can install ``vendor-reset`` using the ``vendor-reset-dkms-git`` package, which will likely not eliminate the issue entirely, but prevents it happening as often. + +It's also worth noting that some cards are affected worse than others, so occurance of the issue may vary. +
diff --git a/docs/RemoteDesktop.md b/docs/RemoteDesktop.md new file mode 100644 index 0000000..2819bc3 --- /dev/null +++ b/docs/RemoteDesktop.md @@ -0,0 +1,79 @@ +## Remote Access and Desktop + +### Both to and from the guest + +#### Introduction + +Various remote access and remote desktop methods provide a way to interact with both your host OS and guest OS, *to and from* either side. This document will go over a couple of methods you can use, and which are best for specific scenarios you may find yourself in. Let's go! + +*** + +#### Access? Desktop? Wat?! + +First of all, I'll quickly define what I mean by "remote access" and "remote desktop". + +**Remote Access** refers to simply accessing the machine over the network remotely - such as Secure Shell (SSH) or a variety of filesharing methods. + +**Remote Desktop** refers to actually *viewing* what's being graphically displayed on the machine - through both physical and virtual display outputs. With this, you can also directly control the machine's mouse and keyboard inputs through your own, if permitted. + +*** + +#### Secure Shell (SSH) + +The quickest and most simple way to remote access into a machine is through SSH. + +SSH allows you to use a terminal emulator on a remote device - such as your phone - to directly execute commands on the target machine. It's essentially like opening a terminal window on your host machine, but displayed on another machine. + +It's especially useful for those with only a single GPU or display - or when passing through an entire USB controller - as you can start and stop virtual machines using commands remotely, even when your host OS is headless. + +| **What it's good for** | **What it isn't good for** | +|:---------------------------------------------:|:--------------------------:| +| Starting and stopping running VMs | File transfer | +| Editing config files through the command line | GUI applications | +| Rebooting your host if necessary | | + +*** + +#### Samba File Sharing (SMB) + +Samba is the most simple and diverse way to access and share files between a variety of OSes. + +You can use Samba to set up SMB shares, that can then be accessed from virtually any operating system, regardless of filesystem. For example, you can set up a share on your Linux host, and access it from within the macOS VM. It can even be set up as read-only if you prefer. + +This is really useful for sharing a unified fileset between your host and guest, or multiple guests. Being able to quickly grab a file from your downloads or a line of code from a project folder is very handy! + +| **What it's good for** | **What it isn't good for** | +|:---------------------------:|:--------------------------:| +| File transfer | Network congestion | +| Accessing files from any OS | Bandwidth | +| Wide compatibility | Bufferbloat | + +*** + +#### ShareMouse + +This is a cross-platform program that lets you share your mouse cursor between machines and OSes seamlessly. + +Many other tools also exist that have similar functionality. + +| **What it's good for** | **What it isn't good for** | +|:--------------------------:|:--------------------------:| +| Continuity | Low latency | +| Ease of use | Performance | +| Share the same USB devices | Stability | + +*** + +#### Virtual Network Computing (VNC) + +VNC is a widely-used and reliable remote desktop protocol. It provides cross-platform desktop viewing and control, and has support built in to several OSes, with virtually all OSes having both a VNC client and server application developed for it. + +VNC is reliable over local networks, and can be port forwarded to access remotely on sufficient internet connections. + +For example, macOS has a VNC server built into the OS. You can enable it in *System Preferences > Sharing > Remote Desktop*. + +| **What it's good for** | **What it isn't good for** | +|:----------------------:|:--------------------------:| +| Basic remote desktop | Intensive workloads | +| Reliability | Gaming | +| Compatibility | Resource usage | \ No newline at end of file